API de tasa impositiva

Instrucciones para la integración técnica con la API de tasa impositiva de LOVAT

Introducción

La siguiente documentación cubre la información sobre los elementos de la API de OMP, incluidas las solicitudes, respuestas y códigos de error.

Para integrar la API de tasa impositiva de OMP:

  1. Registre una cuenta de Lovat OMP.
  2. Complete un perfil de empresa.
  3. Elija un plan.
  4. Configure webhooks.
  5. Obtenga un token.
  6. Establezca reglas impositivas.

Términos y abreviaturas

API: interfaz de programación de aplicaciones. Un conjunto de llamadas proporcionadas por el sistema para la integración con productos de software externos.

Comerciante: el propietario de una tienda en línea.

Cliente: una persona que paga bienes o servicios.

Transacción: transferencia de fondos por bienes o servicios recibidos por el cliente del comerciante.

Token: una cadena secreta utilizada por el sistema para identificar al comerciante y el sitio web a través del cual se registra la transacción.

Referencia de API

La API de Lovat utiliza la arquitectura REST. La API tiene URL predecibles y orientadas a recursos y utiliza códigos de respuesta HTTP para indicar errores de API. La API siempre responde en formato JSON, incluidos los casos de errores.

Autenticación

La autenticación a la API de tasa impositiva se realiza a través de la autenticación básica del encabezado HTTP. Los suscriptores deben proporcionar un token como valor de autenticación básica. Si no tienes experiencia en Lovat, tendrás que registrarte para obtener una cuenta y obtener tu clave API. La API utiliza funciones HTTP integradas, como autenticación HTTP y verbos HTTP, que pueden ser interpretados por clientes HTTP estándar. También admite el uso compartido de recursos de origen cruzado, lo que te permite acceder a ellos de forma segura desde una aplicación web cliente.

URL

La API de Lovat utiliza las siguientes rutas de puntos finales:

  • Región de producción:
https://merchant.vatcompliance.co/api/1/tax_rate  — Tax Rate API
  • Región de prueba:
sandbox.vatcompliance.co/api/1/tax_rate

Método

Tipo de solicitud: POST

https://merchant.vatcompliance.co/api/1/tax_rate/{access_token}

Parámetros JSON

Parámetro Tipo Descripción Requerido
transaction_id Cadena Máximo 255 caracteres opcional

сurrency

 

Cadena

 

Moneda de transacción. Código de moneda de tres letras según ISO 4217 opcional
If_digital Bol Requerido para servicios digitales opcional
transaction_sum Flotar Importe total del pedido de compra opcional
delivery_fee Flotar Importe total del envío del pedido opcional

arrival_country

 

Cadena

 

Un país al que se envió el pedido. Código de país de tres letras mayúsculas según la norma ISO 3166-1 alfa-3 requerido
arrival_zip Cadena Requerido para pedidos en EE. UU.: código postal al que se envió el pedido requerido para los pedidos de EE.UU.
arrival_state Cadena Para EE. UU., Canadá y el Reino Unido: código ISO de dos letras del estado al que se envió el pedido opcional
departure_country Cadena Código ISO de tres letras del país desde el que se envió el pedido. Todos los países se especifican como cadenas de acuerdo con la norma ISO 3166-1 alfa-3

opcional

 

departure_zip Cadena Para pedidos de EE. UU.: código postal desde donde se envió el pedido opcional
departure_state Cadena Para EE. UU. y Canadá: código ISO de dos letras del estado desde donde se envió el pedido opcional
service_code Cadena Obligatorio para los servicios prestados digitalmente. Categorías fiscales de los servicios digitales opcional
good_code Cadena Código de una mercancía según el sistema de codificación de ocho dígitos de la UE La Nomenclatura Combinada (NC) opcional
vat_number_of_buyer Cadena Número de identificación fiscal del comprador opcional
buyer_ip Cadena Dirección IP del comprador. Necesaria para servicios digitales requerido para servicios digitales
exemption_type Cadena Solo para pedidos de EE. UU. opcional
phone_number_of_buyer Cadena Opcional para servicios digitales. Al menos los primeros 5 dígitos deben ser el código del país. opcional
bank_country_of_buyer Cadena Opcional para servicios digitales. Código de país de tres letras mayúsculas según ISO 3166-1 alfa-3 opcional

Lista de errores

Lista de errores HTTP admitidos:

200, 201, 204
Sin error

400 Solicitud incorrecta
Esto suele indicar que falta un parámetro obligatorio. Consulte el cuerpo de la respuesta para obtener más detalles

401 No autorizado
No se proporcionó ninguna clave de API válida

402 Solicitud fallida
La solicitud falló a pesar de los parámetros válidos

403 Prohibido
Sin permiso. Consulte el cuerpo de la respuesta para obtener más detalles

404 No encontrado
El elemento solicitado no existe

409, 422
Parámetros de solicitud no válidos

412 Condición previa fallida
El proyecto aún no se ha activado (se utilizó en el método Obtener token)

415 Tipo de medio no admitido
Falta «Content-Type: application/json» en el encabezado HTTP

500, 502, 503, 504 Errores del servidor
Algo salió mal

Ejemplo de solicitud de consulta

Ejemplo de solicitud desde la consola:

curl-v GET https://merchant.vatcompliance.net/api/1/VAT_rate/get/5aae918d97964ff88df64b059c2cc0f8
--header "Content-Type: application/json" \
-d '{
   "arrival_country": "ITA",
  "departure_country": "GBR",
   "transaction_id": "7668999765",
  "transaction_sum": 10,
  "vat_number_of_buyer": "IT8996543"
}'
{
  "arrival_country": "GBP",
  "currency": "EUR",
  "delivery_fee": 0,
  "departure_country": "HUN",
"vat_number_of_buyer": "IT8996543",
  "transaction_datetime": "2021-01-09",
  "transaction_id": "45000098"
}
{
  "arrival_country": "USA",
  "arrival_state": "NY",
  "arrival_zip": "10034",
  "departure_country": "USA",
  "departure_state": "TX",
  "departure_zip": "77554",
  "transaction_datetime": "2021-01-01",
  "transaction_id": "788654333"
}

Elementos de respuesta

Parámetro Tipo/Ejemplo Descripción
transaction_type “export/import”, “b2c_distance_sales”, “reverse_charge”  
transaction_jurisdiction “ITA”, “GBR” Código ISO de tres letras del país en el que el pedido está sujeto a impuestos. Todos los países se especifican como cadenas de acuerdo con la norma ISO 3166-1 alfa-3
taxable_state “NY” Para EE. UU., Canadá y el Reino Unido: código ISO de dos letras del estado donde el pedido está sujeto a impuestos
sales_tax_rate 8 Tasa de impuesto sobre las ventas
vat_rate 20 Tasa de IVA
export_country “USA”, “GBR” País de exportación para pedidos con tipo de transacción exportación/importación
import_country “USA”, “GBR” País de importación para pedidos con tipo de transacción exportación/importación

Ejemplo de respuesta

{
  "transaction_type": "b2c_distance_sales",
  "taxable_jurisdiction": "USA",
  "taxable_state": "NY",
  "sales_tax_rate": 8.25
}
{
  "transaction_type": "export/import",
  "taxable_jurisdiction": "GBR",
  "vat_rate": 0,
  "export_country": "GBR",
  "import_country": "ITA"
}
{
  "transaction_type": "reverse_charge",
  "taxable_jurisdiction": "FRA",
  "vat_rate": 0
}

Formato de fecha

Todas las fechas se especifican como cadenas de acuerdo con la norma ISO 8601. Puede especificar cadenas de fecha en UTC (p. ej., 2013-01-15T00:00:00Z) o indicando la diferencia horaria con UTC (p. ej., 2013-01-15T00:00:00-08:00 para ocho horas por detrás de UTC). En este último caso, asegúrese de tener en cuenta el horario de verano, si corresponde.

Países

Ofrecemos asistencia en los siguientes países del mundo: EE. UU., países de la UE, Reino Unido, Rusia, Ucrania, Bielorrusia, Noruega, Canadá, Australia, Japón.

Categorías impositivas de los servicios digitales

Contenido audiovisual 1
Transmisión en vivo 2
Servicios telefónicos 3
Servicios de telefonía por Internet 4
Servicios de gestión de llamadas 5
Servicios de paginación 6
acceso a Internet 7
Imágenes 8
Música 9
Juegos 10
Periódicos electrónicos 11
Alojamiento web 12
Mantenimiento de programas a distancia 13
Espacio publicitario en un sitio web 14
Libros electrónicos 15
Licencias 16
Tener una cita 17
Educación a distancia 18
Juego 19

Limitación de llamadas

Limitamos las solicitudes de API a 1000 por minuto para los planes comerciales. Es posible que tenga más llamadas que el límite de su plan mensual. Los cargos por excedente se cobran por separado si excede el límite de su plan durante el mes siguiente.

Tipos de exención

Solo para pedidos en EE. UU., tipos de exención: mayorista, gobierno, mercado, otros, no exentos o nulos.