Integrações

API de Estoque

Publique o estoque dos seus clientes no portal Carro 7 direto do seu sistema. REST, JSON, uma chave por loja.

Para quem é esta API

Para softwares de gestão de revenda: se o seu sistema já controla o estoque da loja, esta API deixa você oferecer o Carro 7 como mais um canal de publicação, do mesmo jeito que você provavelmente já faz com outros portais.

Quem liga a integração é o lojista, dentro do painel do Carro 7. Ele gera uma chave e cola no seu sistema. Você não precisa de cadastro, contrato de API, OAuth nem aprovação nossa para começar a desenvolver — a chave de um cliente seu é tudo que existe.

O contrato em uma frase

Isso vale nos dois sentidos, e o segundo é o que costuma ser esquecido: anúncio que você não mandar mais não sai do ar sozinho. Diferente de um feed XML, aqui não temos como saber que um carro sumiu do seu estoque — a menos que você avise. É para isso que existem o DELETE e a reconciliação.

A chave de integração

O caminho que o seu cliente vai percorrer:

1. No painel do Carro 7, ele abre Integrações → Receber estoque do meu sistema.
2. Informa qual software usa e clica em gerar. Aparece uma chave começando com esk_.
3. Ele copia essa chave e cola no seu sistema, no campo que você criar para o Carro 7.

A chave vale para uma loja. Se o mesmo cliente tem três lojas no Carro 7, são três chaves — guarde-as por loja no seu cadastro. Ela não expira e não precisa ser renovada; o lojista pode revogá-la a qualquer momento pelo painel, e nesse caso as chamadas passam a responder 401.

Uma consequência prática: se a loja tiver anúncios publicados em portais externos pelo Carro 7, a ativação é recusada até que ela os baixe. Sem isso, aqueles anúncios ficariam no portal sem ninguém para removê-los quando o carro fosse vendido — e o seu sistema publicaria outro por cima.

Fundamentos

Base

https://integracao.carro7.com.br/v1

Autenticação

A chave vai no header Authorization, em toda chamada:

Authorization: Bearer esk_1a2b3c...

Confirme que está tudo certo antes de mandar carro — este endpoint existe só para isso:

curl -s https://integracao.carro7.com.br/v1/ping \
  -H "Authorization: Bearer esk_1a2b3c..."

{
  "dados": {
    "autenticado": true,
    "loja": { "id": 23, "nome": "Estoril Veículos" },
    "integrador": "Loja Conectada",
    "servidor_em": "2026-08-07T21:14:03-03:00"
  }
}

Formato das respostas

Sucesso vem sempre dentro de dados; erro, dentro de erro. Nunca há 200 com erro dentro.

{ "dados": { ... } }

{ "erro": { "codigo": "validacao", "mensagem": "...", "detalhes": { "preco": "..." } } }

Limites

Um lote leva 50 anúncios e o limite é por minuto, então o teto prático é da ordem de milhares de carros por minuto — folga suficiente para a carga inicial de uma revenda grande.

Toda resposta traz X-Request-Id

Guarde esse valor no seu log. Ele é o número de protocolo: com ele conseguimos dizer exatamente o que chegou aqui e o que foi feito. Sem ele, "mandei e não entrou" não tem como ser investigado.

Endpoints

POST/v1/anuncios

Cria ou atualiza até 50 anúncios de uma vez. É o endpoint que você vai usar no dia a dia.

curl -s -X POST https://integracao.carro7.com.br/v1/anuncios \
  -H "Authorization: Bearer esk_1a2b3c..." \
  -H "Content-Type: application/json" \
  -d '{
    "anuncios": [
      {
        "ref": "A-1042",
        "marca": "Honda",
        "modelo": "Civic",
        "versao": "2.0 EXL CVT",
        "ano_fabricacao": 2020,
        "ano_modelo": 2021,
        "km": 45000,
        "preco": 118900.00,
        "cambio": "CVT",
        "combustivel": "Flex",
        "cor": "Prata",
        "portas": 4,
        "placa": "ABC1D23",
        "unico_dono": true,
        "descricao": "Revisões em concessionária, pneus novos.",
        "opcionais": ["Ar Condicionado", "Rodas Liga Leve", "Câmera de ré"],
        "fotos": [
          "https://seusistema.com.br/fotos/1042/1.jpg",
          "https://seusistema.com.br/fotos/1042/2.jpg"
        ]
      }
    ]
  }'

A resposta traz uma linha por anúncio, na mesma ordem:

{
  "dados": {
    "recebidos": 3,
    "criados": 1, "atualizados": 1, "removidos": 0, "recusados": 1,
    "resultados": [
      { "ref": "A-1042", "resultado": "criado", "veiculo_id": 8871,
        "situacao": "aguardando_fotos" },

      { "ref": "A-1043", "resultado": "atualizado", "veiculo_id": 8712,
        "situacao": "no_ar",
        "avisos": ["combustivel ausente; assumido \"flex\"."] },

      { "ref": "A-1044",
        "erro": { "codigo": "validacao",
                  "mensagem": "Anúncio recusado. Confira os campos em \"detalhes\".",
                  "detalhes": { "preco": "Informe um preço maior que zero..." } } }
    ]
  }
}

PUT/v1/anuncios/{ref}

O mesmo que o lote, para um anúncio só. Útil quando o seu sistema dispara a atualização a cada alteração do cadastro. O ref da URL é o que vale; se o corpo trouxer outro, ele é ignorado.

Responde 201 quando cria e 200 quando atualiza.

curl -s -X PUT https://integracao.carro7.com.br/v1/anuncios/A-1042 \
  -H "Authorization: Bearer esk_1a2b3c..." \
  -H "Content-Type: application/json" \
  -d '{
    "marca": "Honda",
    "modelo": "Civic",
    "versao": "2.0 EXL CVT",
    "ano_fabricacao": 2020,
    "ano_modelo": 2021,
    "km": 46200,
    "preco": 115900.00,
    "cambio": "CVT",
    "combustivel": "Flex",
    "cor": "Prata",
    "portas": 4,
    "placa": "ABC1D23",
    "unico_dono": true,
    "descricao": "Revisões em concessionária, pneus novos.",
    "opcionais": ["Ar Condicionado", "Rodas Liga Leve"],
    "fotos": ["https://seusistema.com.br/fotos/1042/1.jpg"]
  }'

DELETE/v1/anuncios/{ref}

Dá baixa no anúncio: ele sai do ar como vendido e é removido também dos portais externos onde o lojista publica pelo Carro 7 (Mercado Livre, OLX, Webmotors e afins).

É idempotente. Ref que não existe responde 200 com "resultado": "nao_encontrado", e não 404 — assim a sua rotina de retentativa por timeout nunca recebe erro na segunda tentativa.

curl -s -X DELETE https://integracao.carro7.com.br/v1/anuncios/A-1042 \
  -H "Authorization: Bearer esk_1a2b3c..."

Você também pode dar baixa mandando "status": "vendido" no próprio anúncio, pelo lote ou pelo PUT — o que for mais simples no seu código.

POST/v1/reconciliacao

Explicada na seção Reconciliação, logo abaixo.

GET/v1/anuncios

Lista o que temos hoje desta loja, para você comparar com o seu estoque sem reenviar tudo. Aceita pagina e por_pagina (padrão 50, máximo 200).

{
  "dados": [
    { "ref": "A-1042", "veiculo_id": 8871, "marca": "Honda", "modelo": "Civic",
      "versao": "2.0 EXL CVT", "ano_modelo": 2021, "km": 45000, "preco": 118900.00,
      "situacao": "no_ar", "fotos": 12,
      "url": "https://carro7.com.br/veiculo/8871-honda-civic",
      "atualizado_em": "2026-08-07T20:41:55-03:00" }
  ],
  "paginacao": { "pagina": 1, "por_pagina": 50, "total": 137, "paginas": 3 }
}

Campos do anúncio

Campo essencial ausente recusa o anúncio. Campo acessório estranho vira aviso e o anúncio entra assim mesmo, com o padrão da tabela. Você não precisa normalizar nada antes de mandar: pode mandar "Automático S-Tronic" em cambio e "Flex Power" em combustivel que a gente resolve.

Como as fotos funcionam

Você manda URLs, não arquivos. Nós baixamos as imagens e as hospedamos — o anúncio no Carro 7 não fica dependendo do seu servidor no ar.

O download acontece fora da requisição, em uma fila que roda a cada poucos minutos. Isso tem duas consequências que você precisa tratar:

1. O anúncio novo não vai ao ar na hora. Ele nasce com "situacao": "aguardando_fotos" e é publicado quando a primeira imagem aterrissa. Anúncio sem foto nenhuma fica aguardando indefinidamente — é regra do portal, não uma falha da integração.
2. Trocar foto não tira o anúncio do ar. Um anúncio que já está publicado continua publicado com as fotos antigas enquanto as novas são baixadas.

Só rebaixamos as imagens quando a lista de URLs muda. Se você reenviar o catálogo inteiro de hora em hora com as mesmas URLs, nada é baixado de novo. Por isso, mantenha as URLs estáveis: trocar o nome do arquivo a cada exportação faz o sistema rebaixar tudo sempre, sem necessidade.

Requisitos das URLs:

• http ou https, portas 80 ou 443;
• acessíveis publicamente, sem login e sem token que expire em minutos;
• JPEG, PNG, WebP ou GIF, até 12 MB por arquivo;
• no máximo 25 por anúncio — é o mesmo limite do cadastro manual no painel.

Reconciliação — a rota que não dá para pular

Como você empurra as mudanças, nós só sabemos o que você conta. Se um DELETE se perder — bug, fila travada, servidor reiniciado no meio da rotina — aquele carro fica no ar para sempre, com preço velho, e ninguém percebe.

A reconciliação é a rede de proteção: você manda a lista completa dos refs que estão ativos no seu sistema, e tudo o que não estiver nela sai do ar como vendido.

curl -s -X POST https://integracao.carro7.com.br/v1/reconciliacao \
  -H "Authorization: Bearer esk_1a2b3c..." \
  -H "Content-Type: application/json" \
  -d '{ "refs": ["A-1042", "A-1043", "A-1051"] }'

{ "dados": { "refs_recebidos": 3, "vendidos": 2 } }

Trava de segurança: lista vazia com estoque no ar é recusada com 422 regra_de_negocio, e nada é dado como vendido. Lista vazia quase nunca é "a loja vendeu tudo" — quase sempre é uma consulta que voltou sem resultado do outro lado. Já vimos um feed de parceiro responder 200 com zero veículos e derrubar o estoque inteiro de uma revenda; esta trava existe por causa daquele dia. Para zerar de verdade, use o DELETE anúncio a anúncio.

Um fluxo que funciona bem

Sobre retentativa: 429 traz Retry-After — respeite. 5xx pode ser retentado com espera crescente. 4xx (fora do 429) é problema no que foi enviado e vai falhar de novo igual: registre e siga, não fique em laço.

Suporte

Dúvida de implementação, comportamento estranho ou pedido de campo novo: integracao@carro7.com.br.

Ao relatar um problema, mande o X-Request-Id da resposta e o ref do anúncio. Com os dois conseguimos ver exatamente o que chegou e o que foi feito.