API de facturas
actividades de certificación y validaciones requeridasComenzar
La API de Facturas es parte de la tríada de APIs relacionadas con la gestión de pedidos de Piezas, Accesorios y Prendas (PA&A), siendo las otras dos la API de Orden de Piezas y la API de entregas.
👉 Tómate el tiempo de leer la sección Orden, Factura y Entrega: La Historia Completa para obtener detalles sobre pedidos de piezas, entregas, facturación y cómo usar las tres APIs para conectarlas todas.
La API de Facturas permite a los concesionarios recuperar una factura utilizando el número de factura que se encuentra en la información del pedido de piezas, que también se muestra en la factura enviada por BRP.
La API de Facturas también proporciona un servicio para recuperar una lista de facturas para un concesionario utilizando un filtro.
La API de Facturas puede utilizarse para recuperar una factura de una unidad.
🛑 ¡Las facturas de unidad devueltas son aquellas entre BRP y el concesionario!
👉 Son las facturas enviadas al concesionario cuando el concesionario compra unidades de BRP.
¿Por dónde empezar? ¡Léeme primero!
Antes de comenzar a trabajar en esta API, debes leer las siguientes secciones si aún no las has revisado:
- Orden, Factura y Entrega: La Historia Completa para obtener una descripción general del proceso de pedido y entrega de repuestos.
Resumen empresarial
Tema | Descripción |
|---|---|
Alcance | Unidad y PA&A (Norteamérica) |
Escenarios |
|
Funcionalidades principales |
|
Procesos empresariales compatibles |
|
Beneficios para los concesionarios |
|
Beneficios para BRP |
|
Información técnica
Características
Tipo de API | Tipo de DSP | Versión DCP | Complejidad |
|---|---|---|---|
Obtener datos de BRP | DMS | V3 - Internacional | Baja |
Enviar datos a BRP | CRM | V4 - Norteamérica | Un poco más |
Transacción con BRP | | | Algo más |
Autenticación
La API está usando Autenticación de Aplicaciones.
Necesitas un token de acceso válido antes de llamar a esta API, o debes llamar a la API de Autenticación de Aplicaciones para obtener uno.
¡El token de acceso es válido por 30 minutos! (1799 segundos)
URL Base
Prueba | https://qa-cloud-api.brp.com/dcp/v4 |
|---|---|
Producción | https://cloud-api.brp.com/dcp/v4 |
Recurso: Factura
Cuando se llama para solicitar una lista de facturas, la API de Facturas devuelve un arreglo de recursos de Factura. Cada recurso de Factura, mostrado a continuación, contiene toda la información de una factura.
Cuando llamas para recuperar una factura específica, la API de Facturas devuelve un único recurso de Factura.
Representación JSON
{
"dealer_no": "0000690885",
"invoice_type": "ZF2P",
"invoice_no": "9060858271",
"invoice_date": "2024-03-20",
"payer": "0000690885",
"tax_amount_value": 0,
"invoice_total": 302.97,
"currency": "USD",
"credit_indicator": false,
"is_cancelled": false,
"items": [
{
"item_no": "003202",
"product_code": "705009190",
"sales_order_no": "1030902201",
"sales_order_item_no": "003202",
"delivery_no": "8501841899",
"delivery_item_no": "000010",
"quantity": 12,
"gross_value": 167.76,
"discount_value": 0,
"net_value": 167.94,
"surcharge_value": 0,
"handling_fees_value": 0.18,
"freight_value": 0,
"consignment_fees_value": 0,
"other_fees_value": 0
},
{
"item_no": "004101",
"product_code": "705010334",
"sales_order_no": "1030902201",
"sales_order_item_no": "004101",
"delivery_no": "8501841899",
"delivery_item_no": "000020",
"quantity": 6,
"gross_value": 134.88,
"discount_value": 0,
"net_value": 135.03,
"surcharge_value": 0,
"handling_fees_value": 0.15,
"freight_value": 0,
"consignment_fees_value": 0,
"other_fees_value": 0
}
],
"last_change_date": "2024-03-20T22:00:42Z"
}Propiedades
Todos los campos numéricos con decimales usan el punto (.) como separador decimal. La coma (,) NO está soportada como separador decimal.
Property | Type | Definition | Notes |
|---|---|---|---|
dealer_no | string | Code that represents the dealer number or other entity number. | Length:10 |
invoice_no | string | Invoice number | Length:10 |
invoice_type | string | Type of invoice. The available values are listed in the Invoice Type table below. |
|
invoice_date | date | The date the sales transaction was billed in ISO 8601 format. | yyyy-mm-dd
|
payer | string | Customer Number (Payer). | Length:10 |
tax_amount_value | number | Total tax amount value of the invoice. | Precision: 0.01 |
invoice_total | number | Total net value of the billing document. | Precision: 0.01 |
currency | string | Document currency. The available values are listed in the Currency table below. | Max Length:3 |
credit_indicator | boolean | Indicates if the invoice is a credit. Value can be true or false. |
|
is_cancelled | boolean | Indicates if the invoice has been canceled. Value can be true or false. |
|
last_change_date | String | Date when the last change was made. | Format: YYYY-MM-DDTHH:MM:SSZ |
items | List of objects |
|
|
items.item_no | string | Item number. |
|
items.product_code | string | Code that uniquely identifies a product. | Max Length: 18 |
items.sales_order_no | string | The sales order document that the item refers to. | Max Length:10 |
items.sales_order_item_no | string | The item in the sales order document that the invoice item refers to. | Max Length:10 |
items.delivery_no | string | The delivery number for the invoiced item. | Max Length: 10 |
items.delivery_item_no | string | The delivery number document that the item refers to. | Max Length: 10 |
items.quantity | number | Invoiced quantity in a sales unit of measure. | Precision: 0.001 |
items.gross_value | number | The gross value of the invoiced item. | Precision: 0.01 |
items.discount_value | number | Discount value of the invoiced item. | Precision: 0.01 |
items.net_value | number | Net value of the invoiced item. | Precision: 0.01 |
items.surcharge_value | number | Surcharge amount. | Precision: 0.01 |
items.handling_fees_value | number | Handling fees. | Precision: 0.01 |
items.freight_value | number | Freight value.
| Precision: 0.01 |
items. consignment_fees_value | number | Consignment fees value. | Precision: 0.01 |
items.other_fees_value | number | Other fee value. | Precision: 0.01 |
Tipos de factura
Código | Descripción |
|---|---|
ZCBR | Nota de crédito por una devolución |
ZF2F | Factura para una unidad |
ZF2P | Factura para una orden PA&A |
ZF2S | Factura por servicio |
ZF2W | Factura de garantía extendida (BEST) |
ZG2 | Nota de crédito |
ZG2R | Nota de crédito - devolución |
ZG2W | Nota de crédito - garantía |
ZL2 | Nota de débito |
ZL2W | Nota de débito - garantía |
ZREP | Crédito por devoluciones |
ZREV | Devolución de vehículo |
ZS1 | Cancelación de factura |
ZS1C | Cancelación de nota de débito |
ZS1W | Cancelar factura - garantía |
ZS2 | Cancelación de nota de crédito |
ZS2W | Cancelar nota de crédito - garantía |
ZVG2 | Nota de crédito - promociones |
ZVL2 | Nota de débito - promociones |
ZVS1 | Cancelación de factura - promociones |
ZVS2 | Cancelación de nota de crédito - promociones |
Limitaciones y restricciones
Formato de número
Todos los campos numéricos con decimales usan el punto(.) como separador decimal. La coma (,) NO está soportada como separador decimal.
Facturas para un Distribuidor
Un distribuidor solo puede recuperar una de sus facturas. El parámetro de encabezado Dealer-Number debe identificar al distribuidor que solicita las facturas, y la API devuelve solo las facturas de ese distribuidor.
Tiempo de espera en la llamada para obtener
La API de Facturas proporciona el servicio LISTA para recuperar facturas basadas en un rango de fechas.
❗ En algunos casos, los criterios utilizados para la llamada al servicio LIST pueden seleccionar demasiadas facturas y la API devuelve un tiempo de espera ❗
👉 Su DMS debe gestionar el tiempo de espera y mostrar un mensaje de error que pida al concesionario cambiar el rango de fechas por uno más reducido.
Referencia de la API
curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9060858271' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME' curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061140338.pdf'
--header 'Dealer-Number: 00006908855' \
--header 'Authorization: Bearer REPLACE_ME'
curl --location 'https://cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2024-06-01'&limit=2 \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'Cómo hacerlo
Esta sección proporciona información sobre cómo obtener resultados específicos con la API.
Obtener una factura para encontrar un pedido de piezas
Usando el número de la factura, obtenga una factura específica. Una vez que se encuentra la factura, el distribuidor puede usar el número de la orden de venta (sales_order_no) para encontrar la orden de repuestos relacionada.
Obtener la factura
curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061140338' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME' Obtener la orden de repuestos
👉 Esta orden de repuestos contiene 116 artículos, y se presenta un resumen.
curl --location 'https://cloud-api.brp.com/dcp/v4/parts/orders?sales_order_no=1031033874&dealer_no=0000690885' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' curl --location 'https://cloud-api.brp.com/dcp/v4/parts/orders?sales_order_no=1031033874&dealer_no=0000690885' \
--header 'Authorization-Dealer: THE_ACCESS_TOKEN' \
--header 'Authorization: Bearer REPLACE_ME' Obtener una factura para encontrar una entrega
Usando el número de factura, obtén una factura específica. Una vez que se encuentra la factura, el concesionario puede usar el número de entrega (delivery_no) para encontrar la entrega relacionada.
👉 A partir del número de entrega, se puede encontrar el pedido de repuestos correspondiente, como se describe en la sección Obtener un Documento de Entrega para Encontrar un Pedido de Repuestos
Obtener la Factura
curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061023211' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME' Obtener la Entrega
curl --location 'https://cloud-api.brp.com/dcp/v4/delivery/8502015519' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME' Obtener la factura de una entrega
Obtener una factura usando un número de entrega.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?delivery_nos=8503004312' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME'Obtener facturas para números de entrega
Obtener una lista de facturas usando una lista de números de entrega.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?delivery_nos=8503004312,8503004404,8503003809' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME'Obtener las facturas de un período
Obtener las facturas para un rango de fechas.
curl --location 'https://cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2025-05-01&invoice_date_to=2025-05-10&limit=3' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'Obtener una factura para una unidad
La API de Facturas se puede utilizar para obtener facturas de unidades. La llamada también se realiza usando el número de factura.
👉 Las facturas devueltas son enviadas por BRP al distribuidor cuando el distribuidor compra unidades a BRP.
❗ No son las facturas del cliente ❗
🚗 Las facturas de unidad se identifican con el tipo de factura ZF2F.
curl --location 'https://cloud-api.brp.com/dcp/v4/invoice/9061034465' \
--header 'Dealer-Number: 0000690885' \
--header 'Authorization: Bearer REPLACE_ME'Obtener facturas de un tipo específico
Al llamar al Obtener facturas endpoint, el parámetro invoice_type puede utilizarse para solicitar facturas de un tipo específico.
Los valores válidos son:
- partes: devuelve las facturas de tipo ZF2P.
- unidades: devuelve las facturas de tipo ZF2F.
- servicio: devuelve las facturas de tipo ZF2S.
❗ Al usar el filtro invoice_type, SOLO se devuelven las facturas listadas arriba.
El siguiente ejemplo muestra una llamada para obtener solo las facturas de repuestos.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2025-01-01&invoice_date_to=2025-05-20&limit=2&invoice_type=parts' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME' Obtener facturas con una lista de tipos
Al llamar al Obtener facturas endpoint, el invoice_types se puede usar para solicitar facturas de tipos específicos.
El parámetro acepta una lista de tipos de facturas, separadas por una coma. La API de Facturas devuelve las facturas con los tipos solicitados.
curl --location 'https://qa-cloud-api.brp.com/dcp/v4/invoices?invoice_date_from=2025-01-01&invoice_date_to=2025-05-01&limit=3&invoice_types=ZCBR%2C%20ZF2F%2C%20ZF2P%2C%20ZF2S%2C%20ZF2W%2C%20ZG2%2C%20ZG2R%2C%20ZG2W%2C%20ZL2%2CZL2W%2CZREP%2C%20%20ZREV%2C%20ZS1%2C%20ZS1C%2C%20ZS1W%2C%20ZS2%2C%20ZS2W%2C%20ZVG2%2C%20ZVL2%2C%20ZVS1%2C%20ZVS2' \
--header 'Dealer-Number: 0000690005' \
--header 'Authorization: Bearer REPLACE_ME' Manejo de errores
Esta sección presenta varios escenarios de llamadas incorrectas o erróneas, que dan como resultado mensajes de error y resultados inadecuados.
400 Solicitud incorrecta
El código de estado 400 suele encontrarse durante el desarrollo y la integración, y no debería recibirse durante las operaciones normales. La respuesta devuelta contiene la información necesaria para corregir el problema.
Muchos problemas pueden causar un código de estado 400; los más comunes se enumeran en la tabla siguiente.
Respuesta | Resolución |
|---|---|
Devuelto si falta el parámetro de encabezado Dealer-Number. {
"status": "400",
"id": "rrt-074faba1d0796ac77-c-ea-24396-616154-1",
"title": "bad_request",
"meta": {
"service": "01",
"detail": "validación de solicitud fallida",
"payload": {
"details": [
{
"message": "El parámetro de encabezado 'Dealer-Number' es obligatorio en la ruta '/invoices' pero no se encontró en la solicitud."
}
]
}
}
} | Actualice su llamada API para añadir el parámetro Dealer-Number en el encabezado. |
Devuelto si falta el número de factura en la consulta. {
"status": "400",
"id": "rrt-074faba1d0796ac77-c-ea-24397-616812-1",
"title": "bad_request",
"meta": {
"service": "00",
"detail": "Ruta no encontrada."
}
} | Asegúrese de incluir un número de factura en la ruta de la consulta. |
✏Devuelto si el número de distribuidor es inválido. {
"status": "400",
"id": "rrt-023ba21d3844ea361-c-ea-4985-19207929-2.1",
"title": "bad_request",
"meta": {
"service": "19",
"detail": "Número de distribuidor inválido"
}
} | Si el distribuidor está usando su DMS, puede que ya no sea un distribuidor BRP. Verifique con ellos y desactive las actualizaciones de inventario de repuestos. Asegúrese de que el número de distribuidor tenga 10 caracteres. Si guarda el número sin el '0' inicial, añada el '0' inicial antes de llamar a la API. |
401 No autorizado
El código de estado de error 401 Unauthorized se devuelve cuando intentas llamar a la API con un access_token expirado.
Tienes que obtener un nuevo access_token con una llamada a la API de Autenticación de Aplicaciones.
El código de estado de error 401 Unauthorized también se devuelve si no solicitó acceso a la API creando un ticket en el Jira de DCP.
Cuando esté listo para comenzar a trabajar en una API, debe crear un ticket de certificación en Jira, tal como se describe en la sección Actividades de Certificación con Jira.
Si ya comenzó a trabajar en una API y perdió el acceso, cree un ticket de soporte como se describe en la sección Abrir un Ticket de Soporte.
404 No Encontrado
El código de estado 404 Not Found se devuelve cuando no se encuentra el número de factura.
{
"status": "404",
"id": "rrt-074faba1d0796ac77-c-ea-24396-616988-1.1",
"title": "not_found",
"meta": {
"service": "97",
"detail": "Invoice 9060002826 not found."
}
}El concesionario puede haber cometido un error al ingresar el número de factura. Debe informar el error al usuario para que pueda intentarlo nuevamente.
Requisitos de DSP
Requisitos funcionales
ID | Tipo | Requisito |
|---|---|---|
1 | Obligatorio | El concesionario debe poder buscar una factura utilizando un número de factura. |
2 | Obligatorio | La factura debe mostrarse al concesionario. |
3 | Obligatorio | El concesionario debe poder abrir una orden de repuestos utilizando el número de orden de venta (sales_order_no) encontrado en una factura. |
4 | Obligatorio | El concesionario debe poder abrir un documento de entrega utilizando el número de entrega (delivery_no) encontrado en una factura. |
5 | Obligatorio | El parámetro de encabezado Dealer-Number debe establecerse en el número BRP del concesionario, y el concesionario no puede modificarlo. |
6 | Opcional | El DMS recupera las facturas de los últimos 3 meses y las guarda en la base de datos del DMS. El concesionario puede ver las facturas cargadas. |
7 | Opcional | El concesionario puede solicitar la versión PDF de una factura utilizando un número de factura. |
Actividades de Certificación
Esta sección presenta todas las actividades de certificación y validaciones que deben completarse para certificar la API.
Aseguramiento de la Calidad
Las pruebas enumeradas en la tabla a continuación deben completarse con éxito en el entorno de prueba antes de que pueda comenzar la fase piloto del distribuidor.
Para estas pruebas, tenemos que usar el número de distribuidor 0000690005
ID | Prueba | Resultado Esperado |
|---|---|---|
1 | Obtener la factura 9061863617 | La factura se carga y se muestra. |
2 | Obtener la lista de facturas con el rango de fechas 2053-01-01 a 2026-03-01 | Se carga una lista de 21 facturas. |
3 | Encontrar la orden de repuestos con el número de orden de venta que aparece en la factura 9061863617 | La orden de repuestos se encuentra y se muestra. |
4 | Obtener el archivo PDF de la factura 9061860929 (Opcional) | Se carga el archivo PDF de la factura. |
Piloto de Distribuidor
La siguiente tabla describe los parámetros y validaciones del piloto de distribuidor.
Parámetro | Valor |
|---|---|
Entorno | Producción |
Número de concesionarios | 1 a 3 |
Duración | 1 semana |
Validación 1 | Proporcionar una lista de 10 a 20 facturas de las facturas recibidas por el concesionario. Proporcionar la captura de pantalla o realizar una demostración en vivo para mostrar al menos 10 facturas tal como las ve el concesionario. |
Validación 2 | Proporcionar los números de órdenes de venta (orden de repuestos) recuperados de las facturas en el Paso 1. Proporcionar la captura de pantalla o realizar una demostración en vivo para mostrar la orden de repuestos vinculada a al menos 10 facturas tal como las ve el concesionario. |
Postman
Esta sección describe lo que está disponible en Postman para explorar la API.
Entornos
Un entorno de Postman está disponible para probar la API de Facturas. Este entorno de Postman contiene las variables que usan las consultas y está configurado para conectarse al entorno de prueba.
Colecciones
La colección DMS - Invoices contiene ejemplos de llamadas API para recuperar facturas.