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:
- Registre una cuenta de Lovat OMP.
- Complete un perfil de empresa.
- Elija un plan.
- Configure webhooks.
- Obtenga un token.
- 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.