API Sellout
- Autenticação
- Recomendações
- Envio de Vendas
- Envio de Clientes
- Envio de Estoque
Autenticação
Saiba mais sobre a autenticação em Documentação API Autenticação
Recomendações
- Enviar até 500 registros por requisição ou 10mb (enviar a maior quantidade possível de uma única vez)
- Limitar o número de envios simultâneos em até 5 threads
Envio de Vendas
As vendas, são todos os tickets (pedidos) gerados, sejam eles concluídos com sucesso ou cancelados.
POST <https://sellout.newtail.com.br/v1/sales/**{store_id}**/**{pos_id}**>
Path Parameters
- store_id: Código da loja onde a venda foi realizada
- pos_id: Código do PDV onde a venda foi realizada (se não existir o pos_id, enviar 0)
Body
Atributo | Descrição | Tipo | Obrig. | Padrão | Recomendado |
---|---|---|---|---|---|
invoice_id | Identificador único da venda | String | Sim | ||
currency | Identifica em qual moeda a venda foi paga | String | Não | BRL | |
total_price | Identifica o total da venda | Float | Sim | ||
sub_total | Identifica o total dos itens da venda sem desconto | Float | Sim | ||
additional_cost | Identifica o total de acréscimo na venda | Float | Não | 0 | |
total_discount | Identifica o total de desconto da venda | Float | Não | 0 | |
shipping_cost | Identifica o total da entrega na venda | Float | Não | ||
channel | Identifica o canal de origem da venda. Exemplos: - ifood - rappi - local - commerce | String | Sim | ||
status | Identifica o status da nota fiscal. - issued: para venda feita com sucesso - cancelled: para venda cancelada | String | Sim | ||
delivery_type | Diz qual é o tipo de entrega do pedido. - delivery: para entrega - pick_up: retirada | String | Sim | ||
purchase_type | Diz qual foi o tipo de compra. - online: para compras feitas online | String | Sim | ||
created_at | Data de criação da venda | String | Sim | ||
customer | Informações do Cliente Final | Object | Não | ||
customer.id | Identificação única do cliente | String | Não | ||
customer.name | Nome do Cliente Final | String | Não | ||
customer.gender | Identifica o gênero do cliente | String | Não | ||
customer.date_of_birth | Identifica a data de nascimento do cliente | String | Não | ||
customer.document | Identifica unicamente o cliente final com o código do registro. ex.: CPF ou CNPJ. | String | Não | ||
Items | Lista de Itens que foram vendidos naquele pedido | Array<Object> | Sim | ||
items[].sku | Identifica unicamente o Produto com um código interno | String | Sim | ||
items[].parent_sku | Identifica unicamente o Produto Pai com um código interno | String | Não | null | |
items[].original_sku | Identifica o produto substituído (caso houver) | String | Não | ||
items[].unit_measurement | Indica como o produto foi vendido. - KG para venda por kilo | String | Sim | ||
items[].name | Indica qual é o nome do produto | String | |||
items[].gtins | Indica a lista de Código de Barras do produto | Array<String> | Sim | ||
items[].total_value | Indica qual foi o valor total vendido do produto. (Quantidade * Preço Unitário) - Discount. | Float | |||
items[].unit_price | Indica qual o Preço por Unidade do Produto | Float | |||
items[].quantity | Indica a quantidade vendida do produto | Float | |||
items[].discount | Indica a valor de desconto dado ao produto | Float | |||
items[].brand | Indica qual é o nome da marca do item vendido | String | Não | Sim | |
items[].categories | Indica quais são as categorias do item vendido | Array<String> | Sim | [] | |
payments[].type | Identifica qual o tipo de pagamento utilizado. * cash | String | Sim | ||
payments[].total | Identifica o total do pagamento | Float | Sim | ||
payments[].card_first_numbers | Identifica o bin do cartão | String | Não | ||
payments[].card_last_numbers | Identifica os últimos dígitos do cartão | String | Não | ||
payments[].autorization_id | Identifica o código de autorização da transação | String | Não | ||
billing_address | Informações do endereço de cobrança | Object | Não | ||
billing_address.street | Identifica a rua | String | Sim | ||
billing_address.reference | Identifica uma possível referência do endereço | String | Não | ||
billing_address.number | Identifica o número | String | Sim | ||
billing_address.neighborhood | Identifica o bairro | String | Sim | ||
billing_address.city | Identifica a cidade | String | Sim | ||
billing_address.region | Identifica a UF | String | Sim | ||
billing_address.country | Identifica o país | String | Não | ||
billing_address.complement | Identifica o complemento | String | Não | ||
billing_address.full_name | Nome do pagador | String | Não | ||
billing_address.document | Documento (RG ou CPF) do responsável pela cobrança | String | Não | ||
shipping_address | Informações do endereço de entrega | Object | Não | ||
shipping_address.street | Identifica a rua | String | Sim | ||
shipping_address.reference | Identifica uma possível referência do endereço | String | Não | ||
shipping_address.number | Identifica o número | String | Sim | ||
shipping_address.neighborhood | Identifica o bairro | String | Sim | ||
shipping_address.postcode | Código postal | String | Não | ||
shipping_address.city | Identifica a cidade | String | Sim | ||
shipping_address.region | Identifica a UF | String | Sim | ||
shipping_address.country | Identifica o país | String | Não | ||
shipping_address.complement | Identifica o complemento | String | Não | ||
shipping_address.full_name | Nome de quem recebeu o pedido | String | Não | ||
shipping_address.main_phone | Telefone de quem recebeu o pedido | String | Não | ||
shipping_address.document | Documento (RG ou CPF) de quem recebeu o pedido | String | Não |
[ { "invoice_id": "53478534", "currency": "BRL", "total_discount": 2.60, "additional_cost": 0.00, "total_price": 48.55, "shipping_cost": 10.0, "sub_total": 38.55, "channel": "whatsapp", "status": "issued", "created_at": "2019-09-13T15:30:25.000-0300", "customer": { "id": "123", "name": "João Silva", "document": "62167733305", "gender": "male", "date_of_birth": "2000-01-01" }, "items": [ { "sku": "01", "gtins": [ "123" ], "name": "banana prata", "quantity": 3.5, "unit_price": 9.70, "total_value": 31.35, "discount": 2.60, "unit_measurement": "kg", }, { "sku": "02", "gtins": [ "7896008100216" ], "name": "coca cola", "quantity": 2.00, "unit_price": 3.60, "total_value": 7.20, "unit_measurement": "un", } ], "shipments": [ { "delivery_type": "delivery", "carrier_id": "123", "items": [ "01", "02" ], "schedule_date": "2022-02-07", "schedule_time_start_at": "14:00", "schedule_time_finish_at": "15:00" } ], "payments": [ { "type": "cash", "total": 48.55, "card_first_numbers": "123456", "card_last_numbers": "4776", "autorization_id": "123" } ], "billing_address": { "street": "Avenida Teste", "reference": null, "number": "1000", "neighborhood": "Bairro", "postcode": "22790707", "city": "Rio de Janeiro", "region": "RJ", "country": "Brasil", "complement": "Casa 2", "full_name": "Joao Souza", "main_phone": null, "document": "12345678910" }, "shipping_address": { "street": "Avenida Teste", "reference": null, "number": "1000", "neighborhood": "Bairro", "postcode": "22790707", "city": "Rio de Janeiro", "region": "RJ", "country": "Brasil", "complement": "Casa 2", "full_name": "Joao Souza", "main_phone": null, "document": "12345678910" } } ]
Envio de Clientes
Envio de informações demográficas dos clientes.
POST <https://sellout.newtail.com.br/v1/customers>
Atributo | Descrição | Tipo | Obrigatório | Padrão |
---|---|---|---|---|
customer_id | Indica qual o identificador único do cliente final | String | Sim | |
gender | Indica qual o sexo do cliente | String | ||
Valores: F ou M | Não | null | ||
birth_date | data de nascimento | String. | ||
Formato: YYYY-MM-DD | Não | null | ||
state | Unidade federativa (estado) | String | ||
ex.: RJ, SP… | Não | null | ||
city | Cidade do Estado | String | ||
Ex.: Rio de janeiro, São Paulo, … | Não | null | ||
district | Bairro | String | ||
Ex.: Copacabana, Madureira, … | Não | null | ||
postal_code | Cep | String | ||
Ex.: 21000000 | Não | null | ||
exists_phone | Indica se o cliente tem telefone de contato cadastrado | Boolean | ||
true ou false | Não | null | ||
exists_email | Indica se o cliente tem email de contato cadastrado | Boolean | ||
true ou false | Não | null |
{ "customer_id": "123", "gender": "F", "birth_date": "2022-01-01", "state": "RJ", "city": "Rio de Janeiro", "district": "Copacabana", "postal_code": "21660000", "exists_phone": true, "exists_email": false }
Envio de Estoque
POST <https://sellout.newtail.com.br/v1/stocks/{store_id}>
Path Parameters
- store_id: Código da loja onde a venda foi realizada
Atributo | Descrição | Tipo | Obrigatório | Padrão |
---|---|---|---|---|
sku | Identifica unicamente o Produto com um código interno | String | ||
ex.: abc123 | Sim | |||
stock | Quantidade de estoque do produto | Float | ||
ex.: 1.5 | Sim | |||
is_dc | indica se este stock é referente a um centro de distribuição | Boolean | ||
true ou false | Não | false | ||
unit_measurement | Indica se o estoque é vendido por KG ou por UN | String | ||
ex.: UN | KG | Não | UN | |
created_at | Indica qual a datahora que estoque foi gerado | String | ||
Formato: iso8601 | ||||
Ex.: 2019-09-13T15:30:25.000-03:00 | Sim |
Respostas com Sucesso
O retorno da requisição terá código HTTP 202 com o seguinte body quando os dados forem enviados com sucesso:
{ "messages": [ "sales will be processed soon" ] }
Erros de Validação
Implementamos o padrão https://datatracker.ietf.org/doc/rfc8927/ nas mensagens de erro:
Em caso de erro de validação será enviado um HTTP 422 com os problemas.
{ "messages": [ { "keyword": "required", "params": { "missingProperty": "invoice_id" }, "message": "must have required property 'invoice_id'" } ] }
Erros Internos
Em caso de erro será enviado um HTTP 5XX com o possível problema.
{
"messages": [
"error message"
]
}
Este artigo foi útil?
Que bom!
Obrigado pelo seu feedback
Desculpe! Não conseguimos ajudar você
Obrigado pelo seu feedback
Feedback enviado
Agradecemos seu esforço e tentaremos corrigir o artigo