API de estoque

Quero integrar o sistema de estoque de veículos da loja à API do Carro Daqui, descrita no fim desta mensagem. Escreva o código da integração na linguagem e no framework do meu projeto (vou mostrar os arquivos que cuidam do estoque).

A integração precisa:
1. Enviar um evento sempre que um veículo for incluído, alterado (preço, fotos, quilometragem, dados) ou vendido/retirado no meu sistema, com o veículo completo.
2. Ler a chave e os códigos de variáveis de ambiente: CARRODAQUI_API_KEY, CARRODAQUI_STORE_ID e CARRODAQUI_CONNECTION_ID. A chave nunca vai para o navegador, para um aplicativo ou para o repositório.
3. Gerar um eventId (UUID v4) novo para cada mudança e guardá-lo com o envio, para reenviar o mesmo eventId quando a requisição falhar por rede, HTTP 429 ou HTTP 500.
4. Manter para cada veículo um sourceVersion que só aumenta (por exemplo, um contador ou o horário da alteração em milissegundos, como texto).
5. Converter os dados do meu sistema para o formato da API: preço em centavos como texto, anos como inteiros e categoria, combustível, câmbio e disponibilidade nos valores aceitos.
6. Tratar as respostas: 202 é sucesso; 400 registra os issues e não repete sem corrigir; 401 e 403 param e avisam; 409 gera um eventId novo; 429 espera o Retry-After; 500 repete com espera crescente e o mesmo eventId.
7. Enviar fora da requisição do usuário (fila ou tarefa em segundo plano), para o sistema não ficar lento se a API demorar.
8. Ter testes da conversão dos dados.

No fim, explique onde configurar as variáveis de ambiente e como testar com um veículo.

# API de estoque do Carro Daqui (versão 1.0)

O sistema da loja envia ao Carro Daqui um evento a cada inclusão, alteração ou venda de veículo.
Documentação para pessoas: https://carrodaqui.com.br/desenvolvedores

## Endpoint

POST https://carrodaqui.com.br/integrations/v1/inventory/events
Cabeçalhos: Authorization: Bearer <CHAVE> e Content-Type: application/json
Corpo de até 3 MB. Limite de 240 requisições por minuto por IP.
A chave, o storeId e o connectionId são gerados pela loja no painel (Integrações › API).

## Evento

| campo | tipo | obrigatório | descrição |
| --- | --- | --- | --- |
| schemaVersion | texto | sim | Sempre "1.0". |
| eventId | UUID | sim | Identifica o envio. Repetir o mesmo envio com o mesmo eventId não duplica nada. |
| storeId | texto | sim | Código da loja, no painel (Integrações › API). |
| connectionId | texto | sim | Código da origem, no painel, junto da chave. |
| occurredAt | data e hora | sim | Quando a mudança aconteceu, em UTC: 2026-10-19T14:30:00Z. |
| vehicle | objeto | sim | O veículo completo, com os campos abaixo. |

## Veículo (campo vehicle)

| campo | tipo | obrigatório | descrição |
| --- | --- | --- | --- |
| externalId | texto, até 150 | sim | Código do veículo no seu sistema. Não mude: é ele que identifica o veículo. |
| sourceVersion | inteiro, em texto | sim | Aumente a cada mudança ("1", "2", "3"…). Versão menor ou igual à atual é ignorada. |
| availability | valor fixo | sim | AVAILABLE (à venda), SOLD (vendido) ou UNAVAILABLE. |
| make | texto, até 80 | sim | Marca. Ex.: Chevrolet. |
| model | texto, até 120 | sim | Modelo. Ex.: Onix. |
| version | texto, até 160 | não | Versão. Ex.: LT 1.0 Turbo. |
| manufactureYear | inteiro | sim | Ano de fabricação, de 1950 até o ano que vem. |
| modelYear | inteiro | sim | Ano do modelo: o de fabricação ou até 2 anos depois. |
| amountInCents | inteiro, em texto | sim | Preço em centavos: R$ 74.990,00 = "7499000". |
| mileageKm | inteiro | sim | Quilometragem, de 0 a 5.000.000. Zero km: 0. |
| bodyType | valor fixo | sim | Categoria (lista abaixo). |
| fuel | valor fixo | sim | Combustível (lista abaixo). |
| transmission | valor fixo | sim | MANUAL, AUTOMATIC ou NONE (embarcações). |
| color | texto, até 60 | não | Cor. |
| doors | inteiro, 2 a 6 | não | Portas. |
| engine | texto, até 80 | não | Motor. Ex.: 1.0 Turbo. |
| plateEnding | 1 dígito | não | Final da placa. |
| features | texto, até 3.000 | não | Opcionais separados por vírgula. Nomes comuns são padronizados: "ar cond." vira Ar-condicionado. |
| conditions | lista de valores fixos | não | Condições (lista abaixo). Aceita também o texto, como "Único dono". |
| description | texto, até 5.000 | não | Texto do anúncio. |
| photos | lista de links | não | Até 30 links HTTPS de imagens. A primeira é a capa. |
| videoUrl | link | não | Link HTTPS do vídeo (YouTube ou arquivo de vídeo). |
| sourceUrl | link | não | Endereço do veículo no site da loja. |
| usageHours | inteiro | não | Embarcações: horas de uso do motor. |
| lengthFeet | inteiro, 5 a 300 | não | Embarcações: comprimento em pés. |

Textos têm os espaços das pontas removidos. Campos fora destas tabelas são ignorados.

## Valores aceitos

bodyType: HATCHBACK (hatch), SEDAN (sedã), SUV (utilitário esportivo), PICKUP (picape), VAN (van ou utilitário), SPORT (esportivo), MOTORCYCLE (moto), TRUCK (caminhão), BOAT (embarcação), OTHER (outro)
fuel: FLEX (flex), GASOLINE (gasolina), ETHANOL (etanol), DIESEL (diesel), ELECTRIC (elétrico), HYBRID (híbrido), CNG (GNV)
conditions: UNICO_DONO (único dono), IPVA_PAGO (IPVA pago), LICENCIADO (licenciado), ACEITA_TROCA (aceita troca), GARANTIA_FABRICA (garantia de fábrica), REVISOES_CONCESSIONARIA (revisões na concessionária), BLINDADO (blindado), ADAPTADO_PCD (adaptado para PcD)
transmission: MANUAL, AUTOMATIC, NONE (embarcações)
availability: AVAILABLE (à venda), SOLD (vendido), UNAVAILABLE (fora de venda)

## Exemplo de corpo

```json
{
  "schemaVersion": "1.0",
  "eventId": "b1ac0961-34c4-41ca-a71e-1a5f9e7a82dc",
  "storeId": "ID_DA_LOJA",
  "connectionId": "ID_DA_ORIGEM",
  "occurredAt": "2026-10-19T14:30:00Z",
  "vehicle": {
    "externalId": "EST-123",
    "sourceVersion": "1",
    "availability": "AVAILABLE",
    "make": "Chevrolet",
    "model": "Onix",
    "version": "LT 1.0 Turbo",
    "manufactureYear": 2023,
    "modelYear": 2024,
    "amountInCents": "7499000",
    "mileageKm": 42000,
    "bodyType": "HATCHBACK",
    "fuel": "FLEX",
    "transmission": "AUTOMATIC",
    "color": "Prata",
    "features": "Ar-condicionado, Câmera de ré, Central multimídia",
    "conditions": [
      "UNICO_DONO",
      "IPVA_PAGO"
    ],
    "photos": [
      "https://cdn.sualoja.com.br/onix-frente.jpg"
    ]
  }
}
```

## Respostas

202: { "receiptId": "...", "eventId": "...", "status": "QUEUED" }. O processamento leva poucos segundos.
Erro: { "error": "...", "code": "...", "issues": [{ "field": "vehicle.amountInCents", "message": "..." }] }
- 400 BAD_USER_INPUT: Algum campo está errado. A lista issues diz qual e por quê.
- 401 UNAUTHENTICATED: Chave ausente, errada ou desligada.
- 403 FORBIDDEN: storeId ou connectionId não são os da chave.
- 409 CONFLICT: O eventId já foi usado com outro conteúdo. Use um eventId novo para cada mudança.
- 429: Muitas requisições. Espere os segundos do cabeçalho Retry-After.
- 500 INTERNAL_SERVER_ERROR: Falha do nosso lado. Reenvie com o mesmo eventId, esperando um pouco mais a cada tentativa.

## Recibo

POST https://carrodaqui.com.br/graphql, com a mesma chave no cabeçalho Authorization e o corpo:
{ "query": "query($c:ID!,$e:String!){eventReceipt(connectionId:$c,eventId:$e){status error attempts appliedAt}}", "variables": { "c": "<connectionId>", "e": "<eventId>" } }
- QUEUED: Recebido, na fila.
- PROCESSING: Sendo aplicado.
- APPLIED: Aplicado ao estoque da loja.
- IGNORED: Sem efeito: versão antiga ou nada mudou.
- FAILED: Não aplicado. O campo error diz o motivo; corrija e envie com novo eventId e versão maior.

## Regras

- Um evento por mudança: Incluiu, mudou preço ou fotos, vendeu: envie o veículo inteiro, com sourceVersion maior.
- Sempre o veículo completo: Não existe envio parcial. Um campo opcional que não vier fica vazio no anúncio.
- Reenvio seguro: Caiu a conexão? Reenvie o mesmo corpo com o mesmo eventId: o recibo é o mesmo e nada duplica.
- Venda e retirada: availability SOLD ou UNAVAILABLE tira o anúncio do site. Voltou a venda: AVAILABLE com versão maior.
- Veículo novo entra como rascunho: A loja publica no painel, em Meu estoque. Mudanças em veículos já publicados valem em segundos.
- Limites: Corpo de até 3 MB e até 240 requisições por minuto por IP.