Informações Técnicas
Esta seção apresenta informações técnicas básicas sobre as APIs DCP para ajudá-lo a iniciar seu desenvolvimento.
Ambientes
Existem dois ambientes disponíveis para chamar as APIs DCP: teste e produção.
A URL base seleciona o ambiente para chamar uma API DCP.
Teste | https://qa-cloud-api.brp.com/dcp |
|---|---|
Produção | https://cloud-api.brp.com/dcp |
Informação importante:
- Os dois ambientes usam conjuntos diferentes de credenciais
- O ambiente de teste às vezes tem dados limitados ou antigos, mas isso não afeta o comportamento da API.
- O ambiente de produção deve ser usado apenas para a fase piloto do revendedor de certificação e uma vez que a API esteja certificada.
Uma vez que você tenha suas credenciais, o ambiente de teste pode ser usado durante suas atividades de desenvolvimento para validar a integração da API DCP em seu DSP.
O ambiente de teste também é usado durante as atividades de certificação descritas na Processo de Certificação seção.
Informações Gerais
Esta seção apresenta informações gerais sobre as APIs DCP.
Formato do Payload da Consulta
Todas as APIs DCP usam um payload JSON para as solicitações e as respostas.
Ao chamar uma API DCP para enviar dados ao BRP, o payload recebido pela API DCP é validado contra uma Especificação OpenAPI (OAS).
Se o payload recebido pela API DCP não corresponder ao OAS, a API DCP retorna um erro 400 Bad Request.
Ao chamar uma API DCP para enviar dados ao BRP, o payload recebido pela API DCP é validado contra uma Especificação OpenAPI (OAS).
Se o payload recebido pela API DCP não corresponder ao OAS, a API DCP retorna um erro 400 Bad Request.
A propriedade do objeto JSON em erro é fornecida no payload de resposta de erro.
Por exemplo, se o payload contiver uma propriedade de data e o formato da data for inválido, a seguinte resposta de erro é recebida.
{
"status": 400,
"id": "rrt-07783bca845d5f9ca-d-ea-4205-62358060-1",
"title": "bad_request",
"meta": {
"service": "01",
"code": "request validation failed",
"errors": {
"details": [
{
"message": "[Path '/date_of_repair'] String \"20223-01-10T14:10:09Z\" is invalid against requested date format(s) [yyyy-MM-dd'T'HH:mm:ssZ, yyyy-MM-dd'T'HH:mm:ss.[0-9]{1,12}Z]: []"
}
]
}
}
}Este erro é geralmente visto durante a integração da API DCP no DSP e é observado durante as fases de testes e certificação.
Formato da Carga Útil da Resposta
A carga útil da resposta retornada pelas APIs do DCP é geralmente preparada usando dados recebidos dos sistemas de backend. Em alguns casos, é feito um mapeamento entre o valor retornado pelo backend e o valor retornado na carga útil da resposta.
Pode acontecer que os valores para um campo na carga útil da resposta não estejam disponíveis, por exemplo, se um valor retornado pelo backend estiver ausente no mapeamento de campo.
Essa situação é gerenciada usando as seguintes regras.
- Todos os campos estão sempre presentes na carga útil.
- Se o campo for uma string e não houver valor a retornar, o campo é definido como uma string vazia (“”).
- Se nenhum valor for retornado para todos os outros tipos de campo, o campo é definido como o null valor. Por exemplo, se um campo for um número ou data e o valor estiver ausente, o null valor é retornado
- Se o campo for um array sem valor a retornar, a carga útil contém um array vazio. Por exemplo: "pricings": [ ]
Caminho: Singular versus Plural
Os caminhos da API do DCP usam a convenção singular/plural.
- Quando o endpoint trabalha em um único objeto, o caminho usa o singular.
- Por exemplo, o caminho é assim ao chamar a Parts API para procurar uma peça
- O plural é usado quando o endpoint trabalha em uma coleção de objetos.
- Por exemplo, ao chamar a Parts API para obter todas as alterações desde uma data específica, o caminho é assim:
Certifique-se de verificar o caminho do endpoint da API no Catálogo de API.
Separador Decimal
Todos os campos numéricos com decimais usam o ponto (.) como o separador decimal. A vírgula (,) é NÃO suportada como um separador decimal.
Paginação
Algumas APIs DCP retornam uma lista de objetos. Por exemplo, a API de Peças retorna um catálogo de peças, e a API de Pedido de Peças Obter serviço pode retornar uma lista de pedidos de peças.
Neste caso, os dados são grandes demais para serem retornados em um único payload de resposta, então paginação é usada para dividir a resposta em muitos payloads.
Um mecanismo é fornecido para o chamador navegar pelas páginas. A resposta contém a links propriedade, que contém as anterior e próxima propriedades para navegar pelas páginas.
,
"links": {
"previous": null,
"next": "https://qa-cloud-api.brp.com/dcp/v4/parts?language=en-US&last_changed_date=1900-01-01&sales_org=3020¤cy=USD&limit=200&page=2"
}Se anterior é nulo, você está na primeira página.
Se próxima é nulo, você está na última página.
Algumas APIs também retornam uma meta propriedade que fornece informações sobre a quantidade de dados retornados, o número de páginas, etc.
"meta": {
"total_records": 72062,
"total_pages": 361,
"current_page": 1,
"limit": 200
}Catálogo da API
As referências técnicas da API DCP estão disponíveis na seção Catálogo de API .
Para cada API DCP, as seguintes seções fornecem todas as informações necessárias sobre a API.
- Introdução: uma introdução à API, incluindo o contexto técnico e de negócios.
- Informações Técnicas: autenticação, resumo de recursos, limites e restrições, etc.
- A Referência da API: os serviços disponíveis com seus parâmetros, carga útil, etc.
- Como fazer: exemplos de como usar a API DCP para realizar uma função.
- Tratamento de Erros: informações sobre como lidar com os erros mais comuns.
- Requisitos DSP: requisitos obrigatórios e opcionais sobre como implementar uma função usando a API DCP. Também contém as atividades de certificação
- Postman: uma descrição dos recursos disponíveis para validar a integração da API DCP usando o Postman.
Características da API
A seção Características de cada API Introdução apresenta as características gerais da API, conforme mostrado abaixo.
As duas características mais importantes são:
- Tipo DSP: indica se um DMS, um CRM, ou ambos usam a API DCP.
- Versão DCP: indica quais versões da API DCP são compatíveis.
Tipo de API | Tipo de DSP | Versão DCP | Complexidade |
|---|---|---|---|
Obter dados do BRP | DMS | V3 - Internacional | Baixo |
Enviar dados para o BRP | CRM | V4 - América do Norte | Um pouco mais |
Transação com BRP | | | Um pouco mais |
Versão DCP
Para a maioria das APIs DCP, você não verá diferenças na carga útil e nas chamadas entre as versões 3 e 4. Para essas APIs DCP, as diferenças estão nos sistemas de backend, que é por isso que as versões da API estão documentadas na mesma seção. A Características seção do Introdução indica quais versões DCP da API são compatíveis.
Se houver diferenças na carga útil e/ou chamadas entre as versões DCP para uma API DCP, as diferentes versões estão documentadas em seções específicas do Catálogo de API.
Por exemplo, a API de Pedido de Peças pode ter uma carga útil ligeiramente diferente entre as V3 - Internacional e V4 - Norte-Americano versões.
Neste caso, haveria duas seções no Catálogo de API:
- API de Pedido de Peças V3
- API de Pedido de Peças V4
Requisitos do DSP
A equipe DCP pode definir requisitos funcionais para o seu DSP para garantir que a integração da API DCP atenda aos objetivos de negócios.
Existem dois tipos de requisitos funcionais que podem ser definidos: obrigatórios e opcionais.
Requisitos Obrigatórios
Um requisito obrigatório é um requisito funcional que deve ser implementado pelo seu DSP.
A implementação do requisito é validada e verificada durante o processo de certificação.
Se um requisito obrigatório não for implementado corretamente, a API DCP não pode ser certificada.
Um exemplo de um requisito obrigatório é que uma API DCP deve ser chamada automaticamente todos os dias para recuperar a última atualização do catálogo de peças.
Requisito Opcional
Um requisito opcional é um requisito funcional que a equipe DCP sugere fortemente que você implemente em seu DSP.
Esses requisitos adicionam valor comercial à integração da API DCP no DSP. No entanto, a equipe DCP está ciente de que o DSP pode ter limitações que impedem a implementação desses requisitos, razão pela qual eles são opcionais.
Postman
A maioria das informações técnicas das APIs DCP inclui um conjunto de objetos Postman: ambiente e coleções.
Para usar esses objetos, você deve exportá-los do espaço de trabalho compartilhado do Postman e importá-los para o seu ambiente de equipe do Postman.
Antes de usar as coleções e consultas, você deve alterar as variáveis de ambiente para usar suas informações.
Você deve alterar todos os valores que começam com "SEU_"
Visão Geral do Tratamento de Erros
O tratamento de erros é um aspecto importante das APIs DCP. Os DSPs que usam as APIs DCP devem implementar um tratamento de erros sólido para fornecer ao revendedor informações significativas.
O Catálogo de APIs fornece a lista de códigos de status específicos que podem ser retornados por uma API e os passos a serem seguidos quando o código de status é recebido.
Códigos de status da resposta
As APIs DCP usam a faixa de códigos de status padrão RFC 9110:
- 2xx (Bem-sucedido): A solicitação foi recebida, compreendida e aceita com sucesso
- 4xx (Erro do Cliente): A solicitação contém uma sintaxe inválida ou não pode ser atendida
- 5xx (Erro do Servidor): O servidor falhou em atender a uma solicitação aparentemente válida
As APIs do DCP retornam os seguintes códigos de status.
Código de Status | Descrição |
|---|---|
200 OK | Indica que a solicitação foi bem-sucedida. O conteúdo enviado em uma resposta 200 depende do método da solicitação. |
400 Solicitação Inválida | Indica que o servidor não pode ou não irá processar a solicitação devido a algo que é percebido como um erro do cliente (por exemplo, sintaxe de solicitação malformada, estrutura de mensagem de solicitação inválida ou roteamento de solicitação enganoso). IMPORTANTE: o Carga Útil da Resposta indica os campos da carga útil da solicitação ou parâmetros de consulta em erro. Se houver muitos campos ou parâmetros inválidos, todos devem ser listados. |
401 Não Autorizado | Indica que a solicitação não foi aplicada porque falta credenciais de autenticação válidas. |
403 Proibido | Indica que o servidor entendeu a solicitação, mas se recusou a atendê-la. Por exemplo, o método PUT pode ser usado para atualizar um objeto que não pode ser atualizado. |
404 Não Encontrado | Indica que o servidor não encontrou os objetos solicitados. |
413 Conteúdo Muito Grande | Indica que o servidor está se recusando a processar uma solicitação porque o conteúdo solicitado é maior do que o servidor está disposto ou é capaz de processar. |
500 Erro Interno do Servidor | Indica que o servidor está ciente de que cometeu um erro ou é incapaz de realizar o método solicitado. |
502 Bad Gateway | Indica que a API recebeu uma resposta inválida de um servidor upstream que acessou ao tentar atender à solicitação. |
504 Tempo de Espera do Gateway | Isso indica que a API não recebeu uma resposta em tempo hábil de um servidor upstream que precisava acessar para completar a solicitação. |
A seção Como Lidar com Erros fornece tratamento genérico de erros para cada código de status utilizado 4xx e 5xx. As especificações detalhadas da API DCP no Catálogo de API fornece tratamento de erros específico para cada código de status.
Carga Útil da Resposta
Para o intervalo de códigos de status de erro 4xx e 5xx, uma carga útil de resposta é retornada para fornecer informações sobre o erro. A carga útil da resposta usa uma estrutura baseada na especificação JSON API para erro especificações, como mostrado na tabela abaixo.
❗❗ O código de status 504 Gateway Timeout retorna uma carga útil de resposta básica, uma vez que a API DCP não pode interceptar o erro ❗❗
{ "fault": { "faultstring": "Gateway Timeout", "detail": { "errorcode": "messaging.adaptors.http.flow.GatewayTimeout" } } }
Propriedade | Tipo | Definição |
|---|---|---|
status | string | O código de status HTTP aplicável a este problema é expresso como um valor de string. |
id | string | Uma string única que identifica a solicitação, gerada pelo Apigee |
título | string | Código que identifica o erro ou a frase de razão Um dos
|
meta | objeto | |
meta.serviço | string | O código de serviço onde o erro se originou. É uma referência interna da API DCP que identifica a API DCP. |
meta.detalhe | cadeia | Detalhes sobre a causa do erro |
meta.carga útil | objeto | A resposta bruta do serviço que causa o erro (opcional) |
Por exemplo, uma chamada para um método GET para obter um número de revendedor inexistente retornaria a seguinte resposta.
{
"status": "400",
"id": "rrt-05cc5cef09974c73d-d-ea-11235-10626775-11.1",
"title": "not_found",
"meta": {
"service": "07",
"detail": "Backend error",
"payload": {
"status": 400,
"errors": [
{
"code": "Vintage",
"title": "PAA Order Validate (API/Method)",
"detail": "Please contact Vintage Parts. See bulletin 123981 or www.vpartsinc.com",
"meta": {
"product_code": "080037100",
"item_id": "2833e5ad-ff54-44c1-9058-af64c955faa9",
"message": "015 - Warning -Please contact Vintage Parts. See bulletin 123981 for item_id = 2833e5ad-ff54-44c1-9058-af64c955faa9 product_code = 080037100 (/BRP/PART_ORDER/062)"
}
}
]
}
}
}Como Lidar com Erros
400 Solicitação Inválida
O código de status 400 Solicitação Inválida é visto principalmente durante a integração e testes de uma API DCP.
O código de status é retornado quando algo na solicitação está faltando ou tem um valor inválido. Por exemplo:
- Um parâmetro de consulta obrigatório está faltando
- Um parâmetro de consulta tem um valor inválido
- Uma propriedade obrigatória do payload está faltando
- Uma propriedade do payload tem um valor inválido
Por exemplo, se a API DCP requer o número do revendedor no payload e a propriedade está faltando, o seguinte é enviado:
{
"status": 400,
"id": "rrt-06edc2039f6ce7033-b-ea-23590-61122983-1",
"title": "bad_request",
"meta": {
"service": "01",
"code": "request validation failed",
"errors": {
"details": [
{
"message": "Object has missing required properties ([\"dealer_no\"]): []"
}
]
}
}
}Se a propriedade do número do revendedor contiver um valor inválido, o seguinte será enviado:
{
"status": 400,
"id": "rrt-0570f8640a6f6ee97-d-ea-31505-59966586-1.1",
"title": "not_found",
"meta": {
"service": "07",
"payload": {
"errors": "Dealer number 12345678 is invalid."
}
}
}Esses erros devem ser corrigidos durante as fases de integração e teste.
❗❗ Não tente reenviar a carga útil após um status 400, a menos que você possa corrigir automaticamente o problema ❗❗
Se a mesma carga útil for enviada sem modificação, o mesmo status 400 será retornado.
No entanto, se o usuário do DSP fornecer um valor de propriedade ou um valor de consulta, o erro deve ser convertido em algo significativo para o usuário.
Observe que para muitas APIs do DCP, o código de status 404 Não Encontrado é retornado quando um objeto não é encontrado.
401 Não Autorizado
Este é simples: você chamou uma API do DCP com o token de acesso errado ou expirado.
{
"status": 401,
"id": "rrt-0debaee1f7de5da53-c-ea-8481-2988956-1",
"title": "unauthorized",
"meta": {
"service": "05",
"detail": "Please verify your credentials or the Bearer token you provided. Contact the DCP team if you need further assistance."
}
}Para resolver este erro:
- Certifique-se de usar as credenciais corretas definidas para o ambiente (teste ou produção)
- Certifique-se de que seu token de acesso seja atualizado regularmente.
Verifique a seção Autenticação e Credenciais para informações sobre as credenciais.
403 Proibido
Este erro é geralmente encontrado apenas durante a integração e testes de uma API DCP.
O 403 Proibido é retornado quando você tenta chamar uma API interna BRP diretamente sem passar pela URL correta da API DCP.
{
"error": {
"id": "rrt-0b8f470f8a6f5fd93-d-ea-17530-62132303-1",
"status": 403,
"code": "Not Allowed",
"title": "Not Allowed to call the API from this origin"
}
}A solução para este erro é atualizar a URL que você está usando para chamar a API DCP.
404 Não Encontrado
Uma API DCP que usa um parâmetro de consulta para encontrar um objeto, como um número de revendedor, número de peça ou VIN, retorna o status 404 Não Encontrado.
{
"status": 404,
"id": "rrt-06edc2039f6ce7033-b-ea-23589-61142930-1.1",
"title": "not_found",
"meta": {
"service": "07",
"detail": "Product code 0126488 not found."
}
}Geralmente, o erro deve ser relatado ao usuário do DSP.
413 Conteúdo Muito Grande
As APIs do DCP estão implantadas no APIGee, que tem um limite de carga útil de 10 MB. Se a carga útil que você enviar for maior que 10 MB, você receberá o código de status 413.
A única maneira de resolver esse erro é garantir que o tamanho da carga útil enviada ao integrar uma API do DCP seja inferior a 10 MB, dividindo-a em várias mensagens.
Observe que as APIs do DCP que provavelmente encontrarão esse erro são as APIs de Inventário de Peças de Revendedores e de Dados de Transações de Varejo.
500 Erro Interno do Servidor
Um sistema de backend retorna o status de Erro Interno do Servidor 500 por muitos motivos, portanto, nenhum tratamento específico é possível.
Se possível, a melhor maneira de lidar com o erro é esperar um pouco (30 a 60 segundos) e chamar a API do DCP novamente.
Geralmente funcionará. Mas se não funcionar, você pode tentar novamente algumas vezes (3 a 5 vezes).
Se ainda não funcionar após muitas tentativas, você deve retornar uma mensagem de erro ao usuário e contatar a equipe do DCP para relatar o erro com o máximo de informações possível. Veja a seção Obtendo Suporte para informações sobre como relatar problemas.
502 Bad Gateway
O 502 Bad Gateway pode ocorrer quando a API DCP chama uma API interna do BRP, que eles chamam de sistema de backend.
Se possível, a melhor maneira de lidar com o erro é esperar um pouco (30 a 60 segundos) e chamar a API DCP novamente.
Geralmente funcionará. Mas se não funcionar, você pode tentar algumas vezes (3 a 5 vezes).
Se ainda não funcionar após muitas tentativas, você deve retornar uma mensagem de erro ao usuário e contatar a equipe DCP para relatar o erro com o máximo de informações possível. Veja a seção Obtendo Suporte para informações sobre como relatar problemas.
504 Gateway Timeout
APIGee tem um tempo limite rígido de 55 segundos. Se o sistema de backend levar cerca de ±50 segundos para retornar uma resposta, o APIGee retorna um código de status 504 Gateway Timeout para o DSP que fez a chamada.
Existem duas maneiras gerais de lidar com esse erro
Aguarde e Tente Novamente
A carga do sistema de backend pode causar o tempo limite. Portanto, aguarde um pouco (30 a 60 segundos) e chame a API DCP novamente.
Geralmente funcionará. Mas se não funcionar, você pode tentar algumas vezes (3 a 5 vezes).
Se ainda não funcionar após várias tentativas, você deve retornar uma mensagem de erro para o usuário.
Aguarde a Conclusão
Para os transações DCP APIs, como Pedido de Peças, não tente novamente a transação!
O tempo limite ocorreu porque o sistema de backend leva mais de ±50 segundos para finalizar a transação, mas a transação ainda está sendo processada.
As APIs de transação DCP fornecem um serviço para obter o status da transação.
Aguarde um momento (60 a 90 segundos) e chame o serviço da API DCP para obter o status da transação.
Se ainda estiver sendo processada, aguarde novamente e chame o serviço da API DCP até que a transação seja finalizada.
Para estar seguro, você pode limitar o número de tentativas a 5 a 10 tentativas.