Skip to content
API/
Vendas
/
/
Retornar o PDF de uma ven...

Vendas (v1)

API para gerenciamento de vendas

Download OpenAPI description
sales-apis-openapi.json
sales-apis-openapi.yaml
Languages
Servers
Servidor de produção
https://api-v2.contaazul.com/
Mock server
https://developers.contaazul.com/_mock/docs/sales-apis-openapi/

v1

Conjunto de recursos para acompanhar e administrar operações relacionadas a vendas - esses recursos incluem retornar os vendedores, retornar a venda por id, atualizar uma venda por id, retornar as vendas por filtro, criar uma nova venda, retornar o PDF de uma venda, excluir vendas em lote e retornar os itens de uma venda pelo id da venda

Operations

Retornar os vendedores

Request

Retorna a lista total de vendedores disponíveis

Security
BearerAuth
curl -i -X GET \
  https://api-v2.contaazul.com/v1/venda/vendedores \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/jsonArray [
idstring(uuid)

id do vendedor

Example: "123e4567-e89b-12d3-a456-426614174000"
nomestring

Nome do vendedor

Example: "João da Silva"
id_legadointeger

id legado do vendedor

Example: 123456
]
Response
application/json
[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "nome": "João da Silva",
    "id_legado": 123456
  }
]

Retornar a venda por id

Request

Security
BearerAuth
Path
idstringrequired

O legacy id ou uuid da venda a ser obtida

Example: 123e4567-e89b-12d3-a456-426614174000
curl -i -X GET \
  https://api-v2.contaazul.com/v1/venda/123e4567-e89b-12d3-a456-426614174000 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/json
clienteobject(ClientePegarVendaPorId)
evento_financeiroobject
notificacaoobject(Notificacao)
natureza_operacaoobject(NaturezaOperacao)
vendaobject(Negociacao)
vendedorobject(Vendedor)
Response
application/json
{
  "cliente": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tipo_pessoa": "Física",
    "documento": "12345678901",
    "nome": "João da Silva"
  },
  "evento_financeiro": {
    "id": "123e4567-e89b-12d3-a456-426614174000"
  },
  "notificacao": {
    "id_referencia": "notificacao-123456",
    "enviado_para": "exemplo@email.com",
    "enviado_em": "2023-12-31T12:00:00Z",
    "aberto_em": "2023-12-31T12:00:00Z",
    "status": "ENVIADO"
  },
  "natureza_operacao": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "tipo_operacao": "VENDA",
    "template_operacao": "VENDA_MERCADORIAS",
    "label": "Venda a Não Contribuinte",
    "mudanca_financeira": true,
    "mudanca_estoque": "ENTRADA_ESTOQUE"
  },
  "venda": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "EM_ANDAMENTO",
    "id_legado": 123456,
    "tipo_negociacao": "VENDA",
    "numero": 1001,
    "id_categoria": "123e4567-e89b-12d3-a456-426614174000",
    "data_compromisso": "2023-12-31",
    "configuracao_de_desconto": { … },
    "composicao_valor": { … },
    "condicao_pagamento": { … },
    "total_itens": { … },
    "observacoes": "Cliente confirmou o prazo de pagamento",
    "id_cliente": "123e4567-e89b-12d3-a456-426614174000",
    "versao": 1,
    "tipo_pendencia": { … },
    "situacao": { … },
    "id_natureza_operacao": "123e4567-e89b-12d3-a456-426614174000",
    "id_centro_custo": "123e4567-e89b-12d3-a456-426614174000",
    "introducao": "Orçamento do produto 1 e serviço 1"
  },
  "vendedor": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "nome": "João da Silva",
    "id_legado": 123456
  }
}

Atualizar uma venda por id

Request

Security
BearerAuth
Path
idstringrequired

O uuid da venda a ser editada

Example: 123e4567-e89b-12d3-a456-426614174000
Bodyapplication/jsonrequired
id_clientestring(uuid)required

uuid do cliente

Example: "550e8400-e29b-41d4-a716-446655440000"
numerointegerrequired

Número da venda

Example: 1
data_vendastring(date)required

Data da venda

Example: "2023-12-31"
situacaostringrequired

Situação da venda

Enum"EM_ANDAMENTO""APROVADO""FATURADO""CANCELADO"
Example: "APROVADO"
observacoesstring

Observações sobre a venda

Example: "Cliente solicitou entrega rápida"
observacoes_pagamentostring

Observações sobre o pagamento

Example: "Pagamento realizado em 3 parcelas"
id_natureza_operacaostring(uuid)

id da natureza da operação

Example: "550e8400-e29b-41d4-a716-446655440000"
versaointegerrequired

Versão da venda é obrigatório na edição

Example: 1
itensArray of objects(ItemVendaRequest)required
itens[].​descricaostring

Descrição do item da venda

Example: "Produto A"
itens[].​quantidadenumber(double)required

Quantidade do item da venda

Example: 2
itens[].​valornumber(double)required

Valor do item da venda

Example: 50
itens[].​idstring(uuid)required

id do item da venda

Example: "550e8400-e29b-41d4-a716-446655440000"
itens[].​valor_custonumber(double)

Valor de custo do item da venda.

Example: 40
composicao_de_valorobject(ValorComposicaoRequest)
condicao_pagamentoobject(CondicaoPagamentoRequest)required
condicao_pagamento.​tipo_pagamentostring

Forma de pagamento

Enum"BOLETO_BANCARIO""CARTAO_CREDITO""CARTAO_DEBITO""CARTEIRA_DIGITAL""CASHBACK""CHEQUE""CREDITO_LOJA""CREDITO_VIRTUAL""DEPOSITO_BANCARIO""DINHEIRO"
Example: "CARTAO_CREDITO"
condicao_pagamento.​id_conta_financeirastring(uuid)

id da conta financeira

Example: "550e8400-e29b-41d4-a716-446655440000"
condicao_pagamento.​opcao_condicao_pagamentostringrequired

Deve ser em um dos três formatos: - 1º: Ex: À vista. - 2º: Ex1: 30, 60, 90. Ex2: 15, 30, 45. - 3º: Ex1: 3x. Ex2: 12x

Example: "À vista"
condicao_pagamento.​nsustring

NSU

Example: "1234567890"
condicao_pagamento.​parcelasArray of objects(ParcelaRequest)required
condicao_pagamento.​parcelas[].​data_vencimentostring(date)required

Data de vencimento

Example: "2023-12-31"
condicao_pagamento.​parcelas[].​valornumber(double)required

Valor da parcela

Example: 100
condicao_pagamento.​parcelas[].​descricaostring

Descrição da parcela

Example: "Parcela 1"
curl -i -X PUT \
  https://api-v2.contaazul.com/v1/venda/123e4567-e89b-12d3-a456-426614174000 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id_cliente": "550e8400-e29b-41d4-a716-446655440000",
    "numero": 1,
    "data_venda": "2023-12-31",
    "situacao": "APROVADO",
    "observacoes": "Cliente solicitou entrega rápida",
    "observacoes_pagamento": "Pagamento realizado em 3 parcelas",
    "id_natureza_operacao": "550e8400-e29b-41d4-a716-446655440000",
    "versao": 1,
    "itens": [
      {
        "descricao": "Produto A",
        "quantidade": 2,
        "valor": 50,
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "valor_custo": 40
      }
    ],
    "composicao_de_valor": {
      "frete": 100,
      "desconto": {
        "tipo": "VALOR",
        "valor": 5
      }
    },
    "condicao_pagamento": {
      "tipo_pagamento": "CARTAO_CREDITO",
      "id_conta_financeira": "550e8400-e29b-41d4-a716-446655440000",
      "opcao_condicao_pagamento": "À vista",
      "nsu": "1234567890",
      "parcelas": [
        {
          "data_vencimento": "2023-12-31",
          "valor": 100,
          "descricao": "Parcela 1"
        }
      ]
    }
  }'

Responses

OK

Bodyapplication/json
idstring(uuid)

uuid da venda editada

Example: "123e4567-e89b-12d3-a456-426614174000"
id_legadointeger

id legado

Example: 123456
Response
application/json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "id_legado": 123456
}

Retornar as vendas por filtro

Request

Lista vendas utilizando filtros fornecidos como parâmetros de consulta

Security
BearerAuth
Query
paginainteger

Página

Default 1
Example: pagina=1
tamanho_paginainteger

Tamanho da página

Default 10
Example: tamanho_pagina=10
campo_ordenado_ascendentestring

Campo para ordenação ascendente. Se informado ele desconsidera o valor do campo_ordenado_descendente. É possível ordenar por numero da venda (NUMERO), pelo nome do cliente (CLIENTE) ou pela data da venda (DATA)

Enum"NUMERO""CLIENTE""DATA"
Example: campo_ordenado_ascendente=numero
campo_ordenado_descendentestring

Campo para ordenação descendente. Se este campo for utilizado, o campo campo_ordenado_ascendente não deverá ser informado. É possível ordenar por numero da venda (NUMERO), pelo nome do cliente (CLIENTE) ou pela data da venda (DATA)

Enum"NUMERO""CLIENTE""DATA"
Example: campo_ordenado_descendente=numero
termo_buscastring

Termo para busca das vendas por nome, email do cliente ou número da venda

data_iniciostring(date)

Data de início da emissão da venda

Example: data_inicio=2023-12-30
data_fimstring(date)

Data final da emissão da venda

Example: data_fim=2023-12-30
data_criacao_destring(date)

Data de início da criação da venda

Example: data_criacao_de=2023-12-30
data_criacao_atestring(date)

Data final da criação da venda

Example: data_criacao_ate=2023-12-31
data_alteracao_destring(date-time)

Data de alteração de (ISO 8601, São Paulo/GMT-3)

Example: data_alteracao_de=2025-10-20T07:59:59
data_alteracao_atestring(date-time)

Data de alteração até (ISO 8601, São Paulo/GMT-3)

Example: data_alteracao_ate=2025-10-29T07:59:59
ids_vendedoresArray of strings(uuid)

ids dos vendedores

ids_clientesArray of strings(uuid)

ids dos clientes

ids_natureza_operacaoArray of strings(uuid)

ids da natureza da operação

situacoesArray of strings

Situações das vendas

tiposArray of strings

Tipos de vendas

origensArray of strings

Origens das vendas

numerosArray of integers

Números das vendas

ids_categoriasArray of strings(uuid)

ids das categorias

ids_produtosArray of strings(uuid)

ids dos produtos

pendenteboolean

Indica se a venda está pendente

totaisstring

Tipo de total de venda. Possiveis valores WAITING_APPROVED, APPROVED, CANCELED, ALL

ids_legado_donosArray of integers

ids legados dos donos

ids_legado_clientesArray of integers

ids legados dos clientes

ids_legado_produtosArray of integers

ids legados dos produtos

ids_legado_categoriasArray of integers

ids legados das categorias

curl -i -X GET \
  'https://api-v2.contaazul.com/v1/venda/busca?pagina=1&tamanho_pagina=10&campo_ordenado_ascendente=numero&campo_ordenado_descendente=numero&termo_busca=string&data_inicio=2023-12-30&data_fim=2023-12-30&data_criacao_de=2023-12-30&data_criacao_ate=2023-12-31&data_alteracao_de=2025-10-20T07%3A59%3A59&data_alteracao_ate=2025-10-29T07%3A59%3A59&ids_vendedores=497f6eca-6276-4993-bfeb-53cbbbba6f08&ids_clientes=497f6eca-6276-4993-bfeb-53cbbbba6f08&ids_natureza_operacao=497f6eca-6276-4993-bfeb-53cbbbba6f08&situacoes=string&tipos=string&origens=string&numeros=0&ids_categorias=497f6eca-6276-4993-bfeb-53cbbbba6f08&ids_produtos=497f6eca-6276-4993-bfeb-53cbbbba6f08&pendente=true&totais=string&ids_legado_donos=0&ids_legado_clientes=0&ids_legado_produtos=0&ids_legado_categorias=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/json
totaisobject(TotaisVenda)

Valores das de vendas com status Aprovado, Cancelado, Esperando aprovação e Total

quantidadesobject(QuantidadesVenda)

Quantidades de vendas com status Aprovado, Cancelado, Esperando aprovação e Total

total_itensinteger

Total de itens

Example: 10
itensArray of objects(Venda)
Response
application/json
{
  "totais": {
    "total": 1000,
    "aprovado": 500,
    "cancelado": 200,
    "esperando_aprovacao": 300
  },
  "quantidades": {
    "total": 10,
    "aprovado": 5,
    "cancelado": 3,
    "esperando_aprovacao": 2
  },
  "total_itens": 10,
  "itens": [
    { … }
  ]
}

Criar uma nova venda

Request

Security
BearerAuth
Bodyapplication/jsonrequired
id_clientestring(uuid)required

id do cliente

Example: "123e4567-e89b-12d3-a456-426614174000"
numerointeger(int64)required

Número da venda

Example: 1001
situacaostringrequired

Situação da venda

Enum"EM_ANDAMENTO""APROVADO"
Example: "EM_ANDAMENTO"
data_vendastring(date)required

Data da venda

Example: "2023-12-31"
id_categoriastring(uuid)

id da categoria

Example: "123e4567-e89b-12d3-a456-426614174000"
id_centro_custostring(uuid)

id do centro de custo

Example: "123e4567-e89b-12d3-a456-426614174000"
id_vendedorstring(uuid)

id do vendedor

Example: "40bbdaa5-65c2-49e9-b892-470fd1093ed3"
observacoesstring

Observações sobre a venda

Example: "Observações sobre a venda"
observacoes_pagamentostring

Observações sobre o pagamento

Example: "Observações sobre o pagamento"
itensArray of objects(ItemVendaRequest)required
itens[].​descricaostring

Descrição do item da venda

Example: "Produto A"
itens[].​quantidadenumber(double)required

Quantidade do item da venda

Example: 2
itens[].​valornumber(double)required

Valor do item da venda

Example: 50
itens[].​idstring(uuid)required

id do item da venda

Example: "550e8400-e29b-41d4-a716-446655440000"
itens[].​valor_custonumber(double)

Valor de custo do item da venda.

Example: 40
composicao_de_valorobject(ValorComposicaoRequest)
condicao_pagamentoobject(CondicaoPagamentoRequest)required
condicao_pagamento.​tipo_pagamentostring

Forma de pagamento

Enum"BOLETO_BANCARIO""CARTAO_CREDITO""CARTAO_DEBITO""CARTEIRA_DIGITAL""CASHBACK""CHEQUE""CREDITO_LOJA""CREDITO_VIRTUAL""DEPOSITO_BANCARIO""DINHEIRO"
Example: "CARTAO_CREDITO"
condicao_pagamento.​id_conta_financeirastring(uuid)

id da conta financeira

Example: "550e8400-e29b-41d4-a716-446655440000"
condicao_pagamento.​opcao_condicao_pagamentostringrequired

Deve ser em um dos três formatos: - 1º: Ex: À vista. - 2º: Ex1: 30, 60, 90. Ex2: 15, 30, 45. - 3º: Ex1: 3x. Ex2: 12x

Example: "À vista"
condicao_pagamento.​nsustring

NSU

Example: "1234567890"
condicao_pagamento.​parcelasArray of objects(ParcelaRequest)required
condicao_pagamento.​parcelas[].​data_vencimentostring(date)required

Data de vencimento

Example: "2023-12-31"
condicao_pagamento.​parcelas[].​valornumber(double)required

Valor da parcela

Example: 100
condicao_pagamento.​parcelas[].​descricaostring

Descrição da parcela

Example: "Parcela 1"
curl -i -X POST \
  https://api-v2.contaazul.com/v1/venda \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id_cliente": "123e4567-e89b-12d3-a456-426614174000",
    "numero": 1001,
    "situacao": "EM_ANDAMENTO",
    "data_venda": "2023-12-31",
    "id_categoria": "123e4567-e89b-12d3-a456-426614174000",
    "id_centro_custo": "123e4567-e89b-12d3-a456-426614174000",
    "id_vendedor": "40bbdaa5-65c2-49e9-b892-470fd1093ed3",
    "observacoes": "Observações sobre a venda",
    "observacoes_pagamento": "Observações sobre o pagamento",
    "itens": [
      {
        "descricao": "Produto A",
        "quantidade": 2,
        "valor": 50,
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "valor_custo": 40
      }
    ],
    "composicao_de_valor": {
      "frete": 100,
      "desconto": {
        "tipo": "VALOR",
        "valor": 5
      }
    },
    "condicao_pagamento": {
      "tipo_pagamento": "CARTAO_CREDITO",
      "id_conta_financeira": "550e8400-e29b-41d4-a716-446655440000",
      "opcao_condicao_pagamento": "À vista",
      "nsu": "1234567890",
      "parcelas": [
        {
          "data_vencimento": "2023-12-31",
          "valor": 100,
          "descricao": "Parcela 1"
        }
      ]
    }
  }'

Responses

OK

Bodyapplication/json
idstring(uuid)

id único da venda

Example: "123e4567-e89b-12d3-a456-426614174000"
id_legadointeger(int64)

id legado necessário para a venda

Example: 123456
id_clientestring(uuid)

id do cliente associado à venda

Example: "123e4567-e89b-12d3-a456-426614174001"
numerointeger(int64)

Número da venda

Example: 1001
origemstring

Origem da venda

Example: "Online"
id_categoriastring(uuid)

id da categoria da venda

Example: "123e4567-e89b-12d3-a456-426614174002"
data_vendastring(date-time)

Data da venda

Example: "2023-10-01T12:00:00Z"
situacaoobject(SituacaoResponse)
pendenciaobject(TipoPendenciaResponse)
valor_composicaoobject(ComposicaoValorResponse)
condicao_pagamentoobject(CondicaoPagamentoResponse)
observacoesstring

Observações sobre a venda

Example: "Cliente solicitou entrega rápida"
id_vendedorstring(uuid)

id do vendedor responsável pela venda

Example: "123e4567-e89b-12d3-a456-426614174003"
versaointeger(int64)

Versão da venda

Example: 1
Response
application/json
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "id_legado": 123456,
  "id_cliente": "123e4567-e89b-12d3-a456-426614174001",
  "numero": 1001,
  "origem": "Online",
  "id_categoria": "123e4567-e89b-12d3-a456-426614174002",
  "data_venda": "2023-10-01T12:00:00Z",
  "situacao": {
    "nome": "Situação Exemplo",
    "descricao": "Descrição da situação exemplo"
  },
  "pendencia": {
    "nome": "AGUARDANDO_CONFIRMACAO",
    "descricao": "Aguardando confirmação"
  },
  "valor_composicao": {
    "valor_bruto": 100,
    "desconto": { … },
    "frete": 10,
    "valor_liquido": 90
  },
  "condicao_pagamento": {
    "id_legado": 123456789,
    "tipo_pagamento": "CARTAO_CREDITO",
    "id_conta_financeira": "550e8400-e29b-41d4-a716-446655440000",
    "opcao_condicao_pagamento": "Parcelado",
    "parcelas": [ … ],
    "observacoes_pagamento": "Pagamento realizado em 3 parcelas",
    "nsu": "1234567890",
    "troco_total": 10.5
  },
  "observacoes": "Cliente solicitou entrega rápida",
  "id_vendedor": "123e4567-e89b-12d3-a456-426614174003",
  "versao": 1
}

Retornar o PDF de uma venda

Request

Gera e retorna um PDF da venda especificada pelo id

Security
BearerAuth
Path
idstring or integerrequired
Example: 123e4567-e89b-12d3-a456-426614174000
One of:
string(uuid)
curl -i -X GET \
  https://api-v2.contaazul.com/v1/venda/123e4567-e89b-12d3-a456-426614174000/imprimir \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/pdf
string(binary)

Excluir vendas em lote

Request

Exclui vendas em lote (máximo de 10 vendas por requisição) especificadas pelos uuids fornecidos

Security
BearerAuth
Bodyapplication/jsonrequired
idsArray of strings(uuid)[ 1 .. 10 ] itemsrequired

Lista de uuids das vendas a serem excluídas

Example: ["123e4567-e89b-12d3-a456-426614174000","123e4567-e89b-12d3-a456-426614174001"]
curl -i -X POST \
  https://api-v2.contaazul.com/v1/venda/exclusao-lote \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": [
      "123e4567-e89b-12d3-a456-426614174000",
      "123e4567-e89b-12d3-a456-426614174001"
    ]
  }'

Responses

OK

Bodyapplication/json
atualizadosinteger

Indica quantidade excluída

Example: 1
ignoradosinteger

Indica quantidade ignorada

Example: 1
Response
application/json
{
  "atualizados": 1,
  "ignorados": 1
}

Retornar os itens de uma venda pelo id da venda

Request

Retorna os itens de uma venda especificada pelo id da venda, com suporte a paginação e ordenação

Security
BearerAuth
Path
id_vendastring(uuid)required

id da venda

Example: 123e4567-e89b-12d3-a456-426614174000
Query
paginainteger

Página

Default 1
Example: pagina=1
tamanho_paginainteger

Tamanho da página

Default 10
Example: tamanho_pagina=10
curl -i -X GET \
  'https://api-v2.contaazul.com/v1/venda/123e4567-e89b-12d3-a456-426614174000/itens?pagina=1&tamanho_pagina=10' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/json
itensArray of objects(Item)
itens_totaisinteger
Example: 25
totaisobject(Totais)
Response
application/json
{
  "itens": [
    { … }
  ],
  "itens_totais": 25,
  "totais": {
    "quantidade_produtos": 1,
    "quantidade_servicos": 1,
    "quantidade_nao_conciliados": 1
  }
}

Retornar o próximo número de venda disponível

Request

Security
BearerAuth
curl -i -X GET \
  https://api-v2.contaazul.com/v1/venda/proximo-numero \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

OK

Bodyapplication/json
integer or null(int64)
Response
application/json
4512645