API de Tasa Tributaria
Instrucción para la integración técnica con la API de tasa tributaria de LOVAT
Introducción
La siguiente documentación cubre la información sobre los elementos de la API (Interfaz de Programación de Aplicaciones) de OMP (Mercado en línea), incluidas solicitudes, respuestas y códigos de error.
Para integrar la API de tasa tributaria OMP:
- Registre una cuenta Lovat OMP.
- Complete un perfil de empresa.
- Elige un plan.
- Configure Webhooks.
- Consigue un token.
- Establezca reglas tributarias.
Términos y Abreviaturas
API – Interfaz de Programación de Aplicaciones. Un conjunto de llamadas proporcionadas por el sistema requiere la integración con productos de software externos.
Merchant – el propietario de una tienda en línea.
Customer – una persona que paga por mercancías o servicios.
Transaction – transferencia de fondos por mercancías o servicios recibidos por el cliente del comerciante.
Token – un string 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 URLs predecibles y orientadas a los 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 de la API de Tasa Tributaria se realiza mediante la autenticación básica del encabezado HTTP. Los suscriptores deben proporcionar un token como valor de autenticación básico. Si es nuevo en Lovat, deberá registrarse para obtener una cuenta para conseguir su clave API. La API utiliza funciones HTTP integradas, como la autenticación HTTP y los verbos HTTP, que pueden ser interpretados por clientes HTTP estándar. También admite el uso compartido de recursos de origen cruzado, lo que le permite acceder a él 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
El 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 | String | Máximo 255 caracteres. | opcional |
| сurrency | String | 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 | Float | Importe total de la orden de compra | opcional |
| delivery_fee | Float | Monto total de envío para el pedido | opcional |
| arrival_country | String | Un país al que se envió el pedido. Código de país de tres letras en mayúsculas según ISO 3166-1 alpha-3 | requerido |
| arrival_zip | String | Requerido para pedidos de EE.UU.: Código postal al que se envió el pedido | requerido para los pedidos de EE.UU. |
| arrival_state | String | Para EE.UU., Canadá, Reino Unido: código de estado ISO de dos letras al que se envió el pedido | opcional |
| departure_country | String | Código de país ISO de tres letras del país desde el que se envió el pedido. Todos los países se especifican como string de acuerdo con ISO 3166-1 alpha-3 | opcional |
| departure_zip | String | Para pedidos de EE.UU.: código postal desde donde se envió el pedido | opcional |
| departure_state | String | Para EE.UU., Canadá: código de estado ISO de dos letras desde donde se envió el pedido | opcional |
| service_code | String | Requerido para servicios suministrados digitalmente. Categorías fiscales de servicios digitales | opcional |
| good_code | String | Código de mercancía según el sistema de codificación de ocho dígitos de la UE – la Nomenclatura Combinada | opcional |
| vat_number_of_buyer | String | Número de impuesto del comprador | opcional |
| buyer_ip | String | Dirección IP del comprador. Requerido para servicios digitales | requerido para servicios digitales |
| exemption_type | String | Solo para pedidos de EE.UU. | opcional |
| phone_number_of_buyer | String | Opcional para servicios digitales. Al menos 5 primeros dígitos consisten en el código de país | opcional |
| bank_country_of_buyer | String | Opcional para servicios digitales. Código de país de tres letras en mayúsculas según ISO 3166-1 alpha-3 | opcional |
Lista de Errores
Lista de errores HTTP admitidos:
200, 201, 204
Sin error
400 Bad Request
Esto a menudo indica que falta un parámetro obligatorio. Consulte el cuerpo de la respuesta para obtener más detalles.
401 Unauthorized
No se proporcionó una clave API válida
402 Request Failed
La solicitud falló a pesar de parámetros válidos
403 Forbidden
Sin permiso. Consulte el cuerpo de la respuesta para obtener más detalles.
404 Not Found
El artículo solicitado no existe
409, 422
Parámetros de solicitud no válidos
412 Precondition Failed
El proyecto aún no se ha activado (utilizado en el método Get Token)
415 Unsupported Media Type
‘Content-Type: application/json’ falta en el encabezado HTTP
500, 502, 503, 504 Server Errors
Algo salió mal
Ejemplo de Solicitud de Consulta
Ejemplo de comandos de la consola de comandos
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 de país ISO de tres letras del país donde el pedido está sujeto a impuestos. Todos los países se especifican como string de acuerdo con ISO 3166-1 alpha-3 |
| taxable_state | “NY” | Para EE.UU., Canadá, Reino Unido: código de estado ISO de dos letras donde el pedido está sujeto a impuestos |
| sales_tax_rate | 8 | Tasa Tributaria sobre 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 |
Respuesta de Ejemplo
{ "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 strings de acuerdo con ISO 8601. Puede especificar strings de fechas en UTC (p. Ej., 2013-01-15T00:00:00Z) o indicando el desplazamiento UTC (p. Ej., 2013-01-15T00:00:00-08:00 durante ocho horas después de UTC). En el último caso, asegúrese de tener en cuenta el horario de verano, si corresponde.
Países
Apoyamos a los siguientes países de todo el mundo: EE.UU., Países de la UE, Reino Unido, Rusia, Ucrania, Bielorrusia, Noruega, Canadá, Australia, Japón.
Categorías Fiscales de Servicios Digitales
| Contenido audio/visual | 1 |
| Transmisión en vivo | 2 |
| Servicios telefónicos | 3 |
| Servicios telefónicos por internet | 4 |
| Servicios de gestión de llamadas | 5 |
| Servicios de radiobúsqueda | 6 |
| Acceso a Internet | 7 |
| Imágenes | 8 |
| Música | 9 |
| Juegos | 10 |
| Periódicos electrónicos | 11 |
| Alojamiento web | 12 |
| Mantenimiento a distancia de programas | 13 |
| Espacio publicitario en un sitio web | 14 |
| Libros electrónicos | 15 |
| Licencias | 16 |
| Citas | 17 |
| Educación a distancia | 18 |
| Juegos de azar | 19 |
Limitación de Llamadas
Limitamos las solicitudes de API a 1.000 por minuto para planes comerciales. Es posible que tenga más llamadas que el límite de su plan mensual. Las tarifas por excedente se cobran por separado durante el próximo mes si excede el límite de su plan.
Tipos de Exenciones
Para pedidos de EE.UU. únicos tipos de exención: mayorista, gobierno, mercado, otros, no exentos o cero.