Documentação da API | Botelho Marketing

Como integrar

Autenticação:

Nossa API REST, utiliza o método de autenticação "Basic Auth", sendo necessário enviar os seguintes cabeçalhos à cada requisição feita:

Authorization: Basic hash_base64(clientId:clientSecret) e Content-Type: application/json

Credenciais:

Para obter as credenciais de acesso à API, acesse o menu "Integração > Credenciais" na área do usuário.

URL da API:

A URL base para envio das solicitações HTTP é:

https://app.botelhomarketing.com.br/api/v1/{endpoint}

Resposta:

Em todas as requisições será retornado um "body" no formato JSON, e também o respectivo código de status HTTP (200,400,etc...)

Endpoints

Os seguintes endpoints estão disponíveis em nossa API:

Produtos

Ação	Método	Endpoint	Observações
Listar Tudo	GET	`produtos`	Cada produto traz `categoria` (com `nome`), `area` (com `nome` e `is_digital`), `tags` e `fotos`
Paginar	GET	`produtos/page/{numeroPagina}`	Limite de 10 resultados por página
Exibir	GET	`produtos/{idProduto}`	Mesmos campos enriquecidos (categoria, area + is_digital, tags)

O catálogo inclui produtos físicos e digitais. Os digitais vêm com area.is_digital = true e suas tags.

Taxonomias

Para montar filtros/menus sem varrer todos os produtos. Todos escopados pela credencial.

Ação	Método	Endpoint	Observações
Áreas	GET	`areas`	Retorna `[{ id_area, nome, is_digital }]`
Categorias	GET	`categorias`	Retorna `[{ id_categoria, nome, id_categoria_pai }]`
Tags	GET	`tags`	Retorna `[{ id_tag, nome, id_tag_pai }]` (hierarquia via `id_tag_pai`)

Pedidos

Ação	Método	Endpoint	Observações
Enviar	POST	`pedidos`	Aceita o cabeçalho opcional `Idempotency-Key`: reenvios com a mesma chave retornam o pedido já criado (sem duplicar)
Listar Tudo	GET	`pedidos`	(nenhuma)
Paginar	GET	`pedidos/page/{numeroPagina}`	Limite de 20 resultados por página
Exibir	GET	`pedidos/{idPedido}`	(nenhuma)
Confirmar	PUT	`pedidos/approve/{idPedido}`	Confirma um pedido Pendente (gera baixa de estoque)
Cancelar	PUT	`pedidos/cancel/{idPedido}`	Cancela pedidos Pendentes ou Confirmados (estorna o estoque)

Exemplos

Confira os seguintes exemplos:

Enviar Pedido

Necessário enviar no "body" da requisição, um objeto JSON com os seguintes dados:

{
    "data_chegada": "2026-08-25",
    "observacoes": "Pedido de teste",
    "destinatario": {
        "nome": "José", // obrigatório para pessoa física
        "sobrenome": "da Silva", // obrigatório para pessoa física
        "cargo": "Auxiliar",
        "tipo_pessoa": "fisica", // fisica ou juridica (letra minúscula e sem acentos)
        "cpf": "999.999.999-99", // disponível apenas para pessoa física
        "cnpj": "", // disponível apenas para pessoa jurídica
        "razao_social": "", // obrigatório para pessoa jurídica
        "nome_fantasia": "", // obrigatório para pessoa jurídica
        "telefone": "11988888888",
        "email": "jose.silva@email.com",
        "endereco": {
            "cep": "05117-080",
            "logradouro": "R. União da Vitória",
            "numero": "40",
            "complemento": "",
            "bairro": "Vila Jaguara",
            "cidade": "São Paulo",
            "uf": "SP",
            "pais": "Brasil"
        }
    },
    "itens": [
        {
            "id_produto": "2",
            "qtd": 2
        },
        {
            "id_produto": "3",
            "qtd": 1
        }
    ]
}

Resposta de Produto

Idempotência (opcional): no POST de pedido, envie o cabeçalho Idempotency-Key: <chave-única>. Se a mesma chave for reenviada, a API retorna o pedido já criado (HTTP 200) em vez de duplicar.

Os endpoints de produto retornam categoria, area (com is_digital) e tags:

{
    "id_produto": "323",
    "nome": "Bloco de Bolso Athos",
    "slug": "bloco-de-bolso-athos",
    "qtd_estoque": "935",
    "categoria": { "id_categoria": "12", "nome": "Impressos", "id_categoria_pai": null },
    "area":      { "id_area": "60", "nome": "Comercial", "is_digital": false },
    "tags": [
        { "id_tag": "5", "nome": "Folder", "id_tag_pai": null },
        { "id_tag": "8", "nome": "Safra 24/25", "id_tag_pai": "5" }
    ],
    "fotos": [ { "id_foto": "326", "url": "https://.../11417.jpg" } ]
}