Docs/Vendas
Vendas
Mesmo fluxo da Dashboard: cria a venda, opcionalmente emite a nota e permite cancelar. Recomendado para recorrência e quando você já tem clientes/produtos no catálogo.
Ver requisitos de autenticaçãoHeaders
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Parâmetros do body
customer
string | objectobrigatórioUUID do cliente cadastrado, ou objeto com name/email/document/address. Prefira UUID na recorrência.
products
arrayobrigatórioItens da venda. Use sku ou id do catálogo; price e quantity por linha.
sku
stringopcionalSKU do produto no catálogo.
id
stringopcionalID do produto no catálogo.
price
numberopcionalPreço unitário (use price, não amount).
quantity
numberopcionalQuantidade.
name
stringopcionalNome (se criar item sob demanda).
type
stringopcionalservice, product ou split.
saleDate
string (ISO 8601)opcionalData da venda.
paymentMethod
stringopcionalForma de pagamento (ex.: pix, credit_card). Padrão: credit_card.
emitWhen
stringopcionalimmediately | after_guarantee | manual. Padrão: immediately.
externalId
stringopcionalIdempotência: mesmo externalId não cria segunda venda.
sendEmail
booleanopcionalEnviar e-mail da nota ao cliente. Padrão: false.
discount
numberopcionalDesconto em reais.
shipping
numberopcionalFrete em reais.
nfse
objectopcionalOverrides de NFS-e (discriminação, competência, etc.).
curl -X POST "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/sales" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"customer": "018f6e3b-0000-0000-0000-000000000001",
"saleDate": "2026-01-15T14:30:00.000Z",
"paymentMethod": "pix",
"emitWhen": "immediately",
"externalId": "pedido-checkout-8899",
"products": [
{
"sku": "PLAN_MENSAL",
"price": 99.9,
"quantity": 1
}
]
}'{
"ok": true,
"data": {
"id": "018f6e3b-1111-1111-1111-111111111111",
"externalId": "pedido-checkout-8899",
"emitWhen": "immediately",
"paymentMethod": "pix",
"customer": {
"id": "018f6e3b-0000-0000-0000-000000000001",
"name": "João da Silva",
"email": "[email protected]"
},
"products": [
{
"sku": "PLAN_MENSAL",
"name": "Assinatura mensal",
"price": 99.9,
"quantity": 1
}
]
}
}{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos falharam na validação de entrada.",
"statusCode": 422
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Query params
page
numberopcionalPágina atual. Padrão: 1.
pageSize
numberopcionalItens por página.
search
stringopcionalBusca textual.
curl -X GET "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/sales?page=1" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"ok": true,
"data": [
{
"id": "018f6e3b-1111-1111-1111-111111111111",
"externalId": "pedido-checkout-8899",
"paymentMethod": "pix",
"total": 99.9
}
],
"pageInfo": {
"page": 1,
"pageSize": 20,
"total": 1
}
}{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos falharam na validação de entrada.",
"statusCode": 422
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Parâmetros de rota
id
string (UUID)obrigatórioIdentificador da venda.
curl -X GET "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/sales/018f6e3b-1111-1111-1111-111111111111" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"ok": true,
"data": {
"id": "018f6e3b-1111-1111-1111-111111111111",
"externalId": "pedido-checkout-8899",
"emitWhen": "immediately",
"paymentMethod": "pix",
"customer": {
"id": "018f6e3b-0000-0000-0000-000000000001",
"name": "João da Silva",
"email": "[email protected]"
},
"products": [
{
"sku": "PLAN_MENSAL",
"name": "Assinatura mensal",
"price": 99.9,
"quantity": 1
}
]
}
}{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos falharam na validação de entrada.",
"statusCode": 422
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Content-Type
stringobrigatórioapplication/json
Parâmetros de rota
id
string (UUID)obrigatórioIdentificador da venda.
Parâmetros do body
customer
string | objectobrigatórioUUID do cliente cadastrado, ou objeto com name/email/document/address. Prefira UUID na recorrência.
products
arrayobrigatórioItens da venda. Use sku ou id do catálogo; price e quantity por linha.
sku
stringopcionalSKU do produto no catálogo.
id
stringopcionalID do produto no catálogo.
price
numberopcionalPreço unitário (use price, não amount).
quantity
numberopcionalQuantidade.
name
stringopcionalNome (se criar item sob demanda).
type
stringopcionalservice, product ou split.
saleDate
string (ISO 8601)opcionalData da venda.
paymentMethod
stringopcionalForma de pagamento (ex.: pix, credit_card). Padrão: credit_card.
emitWhen
stringopcionalimmediately | after_guarantee | manual. Padrão: immediately.
externalId
stringopcionalIdempotência: mesmo externalId não cria segunda venda.
sendEmail
booleanopcionalEnviar e-mail da nota ao cliente. Padrão: false.
discount
numberopcionalDesconto em reais.
shipping
numberopcionalFrete em reais.
nfse
objectopcionalOverrides de NFS-e (discriminação, competência, etc.).
curl -X PUT "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/sales/018f6e3b-1111-1111-1111-111111111111" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
-H "Content-Type: application/json" \
-d '{
"customer": "018f6e3b-0000-0000-0000-000000000001",
"products": [{ "sku": "PLAN_MENSAL", "price": 99.9, "quantity": 1 }],
"paymentMethod": "pix"
}'{
"ok": true,
"data": {
"id": "018f6e3b-1111-1111-1111-111111111111",
"externalId": "pedido-checkout-8899",
"emitWhen": "immediately",
"paymentMethod": "pix",
"customer": {
"id": "018f6e3b-0000-0000-0000-000000000001",
"name": "João da Silva",
"email": "[email protected]"
},
"products": [
{
"sku": "PLAN_MENSAL",
"name": "Assinatura mensal",
"price": 99.9,
"quantity": 1
}
]
}
}{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos falharam na validação de entrada.",
"statusCode": 422
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Parâmetros de rota
id
string (UUID)obrigatórioIdentificador da venda.
curl -X POST "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/sales/018f6e3b-1111-1111-1111-111111111111/emit-invoice" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"ok": true,
"data": {
"saleId": "018f6e3b-1111-1111-1111-111111111111",
"status": "processing"
}
}{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos falharam na validação de entrada.",
"statusCode": 422
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Parâmetros de rota
id
string (UUID)obrigatórioIdentificador da venda.
curl -X POST "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/sales/018f6e3b-1111-1111-1111-111111111111/cancel-invoice" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"ok": true,
"data": {
"saleId": "018f6e3b-1111-1111-1111-111111111111",
"status": "canceled"
}
}{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos falharam na validação de entrada.",
"statusCode": 422
}Headers
X-Api-Key
stringobrigatórioChave de API da conta (id do usuário).
X-Api-Secret
stringobrigatórioSegredo da chave de API.
Parâmetros de rota
id
string (UUID)obrigatórioIdentificador da venda.
curl -X DELETE "https://api.emitfy.com/v1/companies/ID_DA_EMPRESA/sales/018f6e3b-1111-1111-1111-111111111111" \
-H "X-Api-Key: SUA_API_KEY" \
-H "X-Api-Secret: SUA_API_SECRET" \
{
"ok": true,
"data": {
"id": "018f6e3b-1111-1111-1111-111111111111",
"deleted": true
}
}{
"ok": false,
"code": "VALIDATION_ERROR",
"message": "Um ou mais campos falharam na validação de entrada.",
"statusCode": 422
}