Skip to content
/
Integração do pedido ao f...

Genius Returns - API reference (1.0.0)

Documentação e referências da api Genius Retuns.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server

https://apidocs.geniusreturns.com.br/_mock/openapi/

Produção

https://integration.geniusreturns.com.br/

QA

https://integration-qa.geniusreturns.com.br/

Segurança

Operações de autenticação e segurança (obtenção do Bearer JWT).

Operations

Processos

Operações para obter, listar, filtrar e criar processos de troca ou devolução.

Operations

Listar processos

Request

Retorna uma lista paginada de processos conforme filtros informados. Observação: os filtros também podem ser enviados no corpo (JSON), conforme exemplo de curl, caso seu cliente HTTP suporte body em requisições GET.

Security
BearerAuth
Query
pageNumberinteger>= 1

Número da página (inicia em 1).

pageSizeinteger>= 1

Quantidade de itens por página.

destring(date)

Data inicial (YYYY-MM-DD).

atestring(date)

Data final (YYYY-MM-DD).

statusinteger

Status do processo (Todos = -1, Pendente = 1, Concluido = 2, Cancelado = 3).

textoBuscastring

Número do pedido, nome/email do cliente ou nº de autorização.

lojaVirtualIdinteger(int64)

Id da loja virtual (sub account).

orderNumberstring

Número do pedido original na loja virtual.

estagioLogisticointeger

Estágio logístico do processo (EProcessLogisticStage).

estagioFinanceirointeger

Estágio financeiro do processo (EProcessFinancialStage).

estagioRatinginteger

Estágio rating do processo (EProcessRatingStage).

Bodyapplication/json
destring(date)

Data inicial (YYYY-MM-DD).

atestring(date)

Data final (YYYY-MM-DD).

statusinteger

Status do processo (Todos = -1, Pendente = 1, Concluido = 2, Cancelado = 3).

textoBuscastring

Número do pedido (e-commerce), nome/email do cliente ou nº de autorização.

lojaVirtualIdinteger(int64)

Id da loja virtual (sub account).

orderNumberstring

Número do pedido original na loja virtual.

estagioLogisticoNenhum (integer) or Pendente1 (integer) or Erro2 (integer) or Loja física3 (integer) or Autorizado4 (integer) or Postado ou coletado5 (integer) or Entregue6 (integer) or Parcialmente Entregue7 (integer)(int32)(EProcessLogisticStage)

Estágio logístico do processo.

Enum ValueDescription
0

Nenhum

1

Pendente

2

Erro

3

Loja física

4

Autorizado

5

Postado ou coletado

6

Entregue

7

Parcialmente Entregue

One of:

Estágio logístico do processo.

integer(int32)(Nenhum)

Estágio logístico do processo.

Enum ValueDescription
0

Nenhum

1

Pendente

2

Erro

3

Loja física

4

Autorizado

5

Postado ou coletado

6

Entregue

7

Parcialmente Entregue

estagioFinanceiroNenhum (integer) or Pendente1 (integer) or Reembolso parcial2 (integer) or Reembolso efetuado3 (integer) or Erro4 (integer)(int32)(EProcessFinancialStage)

Estágio financeiro do processo.

Enum ValueDescription
0

Nenhum

1

Pendente

2

Reembolso parcial

3

Reembolso efetuado

4

Erro

One of:

Estágio financeiro do processo.

integer(int32)(Nenhum)

Estágio financeiro do processo.

Enum ValueDescription
0

Nenhum

1

Pendente

2

Reembolso parcial

3

Reembolso efetuado

4

Erro

estagioRatingPendente (integer) or Parcial1 (integer) or Completo2 (integer)(int32)(EProcessRatingStage)

Estágio de rating do processo.

Enum ValueDescription
0

Pendente

1

Parcial

2

Completo

One of:

Estágio de rating do processo.

integer(int32)(Pendente)

Estágio de rating do processo.

Enum ValueDescription
0

Pendente

1

Parcial

2

Completo

curl --location --request GET 'https://integration.geniusreturns.com.br/v3/pvt/processo/listar?pageNumber=1&pageSize=10' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
--header 'Content-Type: application/json' \
--data '{
    "de": "2025-05-01",
    "ate": "2025-05-28",
    "textoBusca": "12372-52025",
    "estagioLogistico": 3
}'

Responses

Lista de processos retornada com sucesso.

Bodyapplication/json
PageSizeinteger
TotalPagesinteger
CurrentPageinteger
TotalRecordsinteger
Datestring(date-time)required

Data e hora da resposta expressa em UTC

ResultArray of objects(ProcessModel)required

Entidade relacionada

Result[].​idinteger(int64)
Result[].​tipointeger

Tipo de Processo: Devolucao = 0, Troca = 1

Enum01
Result[].​tipoFreteEstornointeger

Tipo de estorno do frete (EPedidoItemEstorno): 0 ValeCompras, 1 Estorno, 2 Estorno automático

Enum012
Result[].​valorDiferencanumber(double)

0: não há diferença; >0: valor a receber do usuário; <0: valor a pagar ao usuário

Result[].​mantenhaOItemboolean or null

True quando a solicitação faz jus à funcionalidade KeepTheItem; do contrário, False

Result[].​statusinteger

Indefinido = -1, Iniciado = 0, Pendente = 1, Concluido = 2, Cancelado = 3

Enum-10123
Result[].​numerostring

Número da solicitação

Result[].​datastring(date-time)

Data da solicitação

Result[].​dadosBancariosDtoobject(DadosBancariosDTO)

Dados bancários do cliente para reembolso quando não for cartão de crédito

Result[].​notaFiscalDevolucaoobject or null

Nota fiscal de devolução

Result[].​pedidoobject(PedidoModel)
Result[].​lojaVirtualobject(LojaVirtualModel)

Loja virtual configurada na plataforma Genius

Result[].​valeCompraobject(ValeCompraModel)

Informações do vale-compra quando a forma de reembolso for vale

Result[].​autorizacoesLRArray of objects(AutorizacaoLogisticaReversaModel)

Coleção de autorizações de logística reversa

Result[].​lojaFisicaobject(LojaFisicaModel)

Dados da loja física quando a devolução ocorre em loja

Result[].​transportadoraobject(TransportadoraModel)

Dados da transportadora quando a forma de envio for transportadora

Result[].​tipoServicoLogisticointeger

Tipo de remessa reversa (EDTipoEntregaReversa): -1 Indefinido, 0 PostagemEmAgencia, 1 ColetaSimples, 2 ColetaSimultanea, 3 Expressa, 4 PostoDeColeta

Enum-101234
Result[].​tipoServicoLogisticoDescricaostring

Descrição do tipo de logística reversa

Result[].​lockerobject(LockerModel)

Dados do locker quando a postagem é em armário inteligente

Result[].​valorLogisticaPremiumnumber or null

Quando logística premium fornecida, valor a ser pago

Result[].​agenteobject(AgenteModel)
Result[].​marketplaceboolean

True se marketplace

Result[].​blocklistboolean

True se em Blocklist

Result[].​cashbackobject(CashbackDataModel)

Dados de cashback, quando cabível

Result[].​progressobject(ProcessProgressModel)

Estágios do processo

Result[].​notasDevolucaoArray of objects(ReturnNoteModel)

Coleção de notas de devolução associadas ao processo

Recordsinteger

Registros retornados

HttpStatusstring

Status http da requisição

Errobject(ApiResponseErro)

Conterá detalhes de um eventual erro

Response
application/json
{
  "PageSize": 0,
  "TotalPages": 0,
  "CurrentPage": 0,
  "TotalRecords": 0,
  "Date": "2019-08-24T14:15:22Z",
  "Result": [
    { … }
  ],
  "Records": 0,
  "HttpStatus": "string",
  "Err": {
    "ErroCodigo": "string",
    "ErroDescricao": "string"
  }
}

Integração do pedido ao fluxo de devolução

Request

Endpoint utilizado para integrar um pedido da loja virtual à plataforma Genius Returns. Um link será disponibilizado pela API e poderá ser utilizado para redirecionar o usuário solicitante à interface Genius Returns de solicitação de troca ou devolução, diretamente ao estágio de seleção itens.

Security
BearerAuth
Bodyapplication/jsonrequired
Pedidoobject(IntegrateRequestOrder)

Pedido para integração do fluxo de solicitação de troca ou devolução

curl -i -X POST \
  https://apidocs.geniusreturns.com.br/_mock/openapi/v3/pvt/processo/integrar/fluxo \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Pedido": {
      "PedidoNumero": "string",
      "PedidoStatus": "string",
      "PedidoId": "string",
      "Cliente": {
        "ClienteNome": "string",
        "ClienteEmail": "string",
        "ClienteTelefone": "string",
        "ClienteCelular": "string",
        "ClienteDocumento": "string",
        "ClienteEndereco": {
          "logradouro": "string",
          "numero": "string",
          "complemento": "string",
          "bairro": "string",
          "cidade": "string",
          "estado": "string",
          "cep": "string",
          "latitude": "string",
          "longitude": "string",
          "obs": "string"
        }
      },
      "PedidoData": "2019-08-24T14:15:22Z",
      "PedidoDataEntrega": "2019-08-24T14:15:22Z",
      "PedidoValorTotal": 0,
      "PedidoValorFrete": 0,
      "PedidoValorDesconto": 0,
      "Skus": [
        {
          "SkuId": "string",
          "SkuNome": "string",
          "SkuReferencia": "string",
          "SkuSellerReference": "string",
          "ProdutoId": "string",
          "ProductRef": "string",
          "ProdutoNome": "string",
          "Preco": 0,
          "PrecoDeLista": 0,
          "Quantidade": 0,
          "Peso": 0,
          "Altura": 0,
          "Largura": 0,
          "Comprimento": 0,
          "SellerId": "string",
          "DocaId": "string",
          "EstoqueId": "string",
          "ImagemAbsUrl": "string",
          "Variacoes": [
            {
              "Nome": "string",
              "Valores": [
                "string"
              ]
            }
          ],
          "InvoiceKey": "string"
        }
      ],
      "Transacoes": [
        {
          "TID": "string",
          "SellerNomeId": "string",
          "Data": "2019-08-24T14:15:22Z",
          "Pagamentos": [
            {
              "PId": "string",
              "TipoPagamento": 0,
              "TipoPagamentoDescricao": "string",
              "Valor": 0,
              "Parcelamento": 0,
              "ValorReferencia": 0,
              "TID": "string",
              "Nsu": "string",
              "Adquirente": "string",
              "Grupo": "string"
            }
          ]
        }
      ],
      "NotasFiscais": [
        {
          "Number": "string",
          "Series": "string",
          "AccessKey": "string",
          "XML": "string",
          "DanfeLink": "string",
          "Data": "2019-08-24T14:15:22Z",
          "File": "string"
        }
      ]
    }
  }'

Responses

OK

Bodyapplication/json
Datestring(date-time)

Data e hora da resposta expressa em UTC

Resultstring

Entidade relacionada

Recordsinteger(int32)

Registros retornados

HttpStatusstring

Status http da requisição

Errobject(ApiResponseErro)

Conterá detalhes de um eventual erro

Response
application/json
{
  "Date": "2019-08-24T14:15:22Z",
  "Result": "string",
  "Records": 0,
  "HttpStatus": "string",
  "Err": {
    "ErroCodigo": "string",
    "ErroDescricao": "string"
  }
}

Importa uma solicitação de troca ou devolução

Request

Security
BearerAuth
Bodyapplication/jsonrequired
Processoobject(ProcessoInputDTO)required

Representa uma solicitação de troca ou devolução.

Processo.​ClienteIPstring

IP do cliente.

Processo.​LojaFisicaIdinteger or null(int64)

Id da Loja Física.

Processo.​LojaFisicaResumostring or null

Resumo Loja Física.

Processo.​TransportadoraIdinteger or null(int64)

Id da Transportadora.

Processo.​ServicoLogisticoIdinteger or null(int64)

Em caso de hub logístico, o id do serviço assinalado será armazenado.

Processo.​HubQuotationIdstring or null
Processo.​HubQuotationValuenumber or null(double)
Processo.​TransportadoraTipoEntregainteger(EDTipoEntregaReversa)

Tipo de entrega transportadora (0 para Postagem em agância, 1 ou 2 para coleta domiciliar, 3 para coleta expressa e 4 para postagem em lockers)

Enum-101234
Processo.​LogisticaPremiumValornumber or null(double)

Quando logística premium fornecido ao cliente, este campo conterá o valor a ser pago.

Processo.​MantenhaOItemboolean or null

True quando a solicitação faz jus à funcionalidade KeepTheItem.

Processo.​ValorEstimadoLRnumber or null(double)

Valor estimado de LR.

Processo.​DadosBancariosDtoobject(DadosBancariosDTO)

Dados bancários do cliente para reembolso quando não for cartão de crédito

Processo.​Pedidoobject(PedidoInputDTO)

Representa um pedido realizado na loja virtual.

Processo.​ValeCompraobject(ValeCompraInputDTO)

Representa um vale-compras.

Processo.​Cashbackobject(CashbackDTO)

Representa um cashback.

Processo.​PostoPostagemobject(PostoPostagemBaseDTO)

Representa um posto para postagem de produtos a serem devolvidos ao lojista (lockers).

Processo.​LojaVirtualobject

Representa a loja virtual em que a solicitação foi feita.

Processo.​Agenteobject

Informado quando um usuário do admin cadastra o processo.

Processo.​NotificarNovaSolicitacaoboolean

true ou false para notificar a nova solicitação.

Processo.​Marketplaceboolean

true se marketplace; do contrário, false.

Processo.​TipoFreteEstornointeger or null

Tipo de estorno do item do pedido: ValeCompras = 0, Estorno = 1, EstornoAutomático = 2.

Enum012
Processo.​ValeComprasBonusboolean

True se vale-compras bonus.

DadosCartaoobject

Dados do cartão, apenas se houver pagamento de entrega expressa.

RotaEntregaExpressaobject

Rota da entrega expressa, apenas se houver entrega expressa.

curl -i -X POST \
  https://apidocs.geniusreturns.com.br/_mock/openapi/v1/pvt/processo/enviar-solicitacao \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "Processo": {
      "ClienteIP": "200.100.50.25",
      "Marketplace": false,
      "NotificarNovaSolicitacao": true,
      "Pedido": {
        "PedidoId": "123456",
        "Data": "2025-09-01T12:00:00Z",
        "Numero": "PED-0001",
        "Valor": 199.9,
        "ValorFrete": 19.9,
        "ValorDesconto": 0,
        "ClienteEcommId": "C123",
        "ClienteNome": "Maria Silva",
        "ClienteEmail": "maria@email.com",
        "ClienteDocumento": "12345678901",
        "ClienteTelefone": "1130000000",
        "ClienteCelular": "11990000000",
        "Parcelas": 1,
        "QuantidadeItens": 1,
        "PossuiValeCompra": false,
        "ClienteEndereco": {
          "Logradouro": "Rua A",
          "Numero": "100",
          "Bairro": "Centro",
          "Cidade": "São Paulo",
          "Estado": "SP",
          "CEP": "01000-000"
        },
        "Skus": [
          {
            "SkuId": "SKU-1",
            "SkuNome": "Camiseta Preta M",
            "ProdutoId": "P-1",
            "ProdutoNome": "Camiseta Preta",
            "Preco": 199.9,
            "PrecoDeLista": 199.9,
            "Estoque": 10,
            "Quantidade": 1,
            "QuantidadeTotal": 1,
            "TipoProcesso": 0,
            "Motivo": {
              "Descricao": "Ficou grande",
              "NaoIncluirFreteNoValorADevolver": false
            }
          }
        ]
      }
    }
  }'

Responses

Objeto ProcessoDTO que representa a solicitação de troca ou devolução.

Bodyapplication/json
DataHoraRespostastring(date-time)required

Data e hora da resposta expressa em UTC.

HttpStatusstring

Código HTTP no formato texto.

Registrosinteger

Quantidade de registros retornados.

Entidadeobject(ProcessModel)required

Objeto principal do processo

Entidade.​idinteger(int64)
Entidade.​tipointeger

Tipo de Processo: Devolucao = 0, Troca = 1

Enum01
Entidade.​tipoFreteEstornointeger

Tipo de estorno do frete (EPedidoItemEstorno): 0 ValeCompras, 1 Estorno, 2 Estorno automático

Enum012
Entidade.​valorDiferencanumber(double)

0: não há diferença; >0: valor a receber do usuário; <0: valor a pagar ao usuário

Entidade.​mantenhaOItemboolean or null

True quando a solicitação faz jus à funcionalidade KeepTheItem; do contrário, False

Entidade.​statusinteger

Indefinido = -1, Iniciado = 0, Pendente = 1, Concluido = 2, Cancelado = 3

Enum-10123
Entidade.​numerostring

Número da solicitação

Entidade.​datastring(date-time)

Data da solicitação

Entidade.​dadosBancariosDtoobject(DadosBancariosDTO)

Dados bancários do cliente para reembolso quando não for cartão de crédito

Entidade.​notaFiscalDevolucaoobject or null

Nota fiscal de devolução

Entidade.​pedidoobject(PedidoModel)
Entidade.​lojaVirtualobject(LojaVirtualModel)

Loja virtual configurada na plataforma Genius

Entidade.​valeCompraobject(ValeCompraModel)

Informações do vale-compra quando a forma de reembolso for vale

Entidade.​autorizacoesLRArray of objects(AutorizacaoLogisticaReversaModel)

Coleção de autorizações de logística reversa

Entidade.​lojaFisicaobject(LojaFisicaModel)

Dados da loja física quando a devolução ocorre em loja

Entidade.​transportadoraobject(TransportadoraModel)

Dados da transportadora quando a forma de envio for transportadora

Entidade.​tipoServicoLogisticointeger

Tipo de remessa reversa (EDTipoEntregaReversa): -1 Indefinido, 0 PostagemEmAgencia, 1 ColetaSimples, 2 ColetaSimultanea, 3 Expressa, 4 PostoDeColeta

Enum-101234
Entidade.​tipoServicoLogisticoDescricaostring

Descrição do tipo de logística reversa

Entidade.​lockerobject(LockerModel)

Dados do locker quando a postagem é em armário inteligente

Entidade.​valorLogisticaPremiumnumber or null

Quando logística premium fornecida, valor a ser pago

Entidade.​agenteobject(AgenteModel)
Entidade.​marketplaceboolean

True se marketplace

Entidade.​blocklistboolean

True se em Blocklist

Entidade.​cashbackobject(CashbackDataModel)

Dados de cashback, quando cabível

Entidade.​progressobject(ProcessProgressModel)

Estágios do processo

Entidade.​notasDevolucaoArray of objects(ReturnNoteModel)

Coleção de notas de devolução associadas ao processo

Response
application/json
{
  "DataHoraResposta": "2019-08-24T14:15:22Z",
  "HttpStatus": "string",
  "Registros": 0,
  "Entidade": {
    "id": 0,
    "tipo": 0,
    "tipoFreteEstorno": 0,
    "valorDiferenca": 0.1,
    "mantenhaOItem": true,
    "status": -1,
    "numero": "string",
    "data": "2019-08-24T14:15:22Z",
    "dadosBancariosDto": { … },
    "notaFiscalDevolucao": {},
    "pedido": { … },
    "lojaVirtual": { … },
    "valeCompra": { … },
    "autorizacoesLR": [ … ],
    "lojaFisica": { … },
    "transportadora": { … },
    "tipoServicoLogistico": -1,
    "tipoServicoLogisticoDescricao": "string",
    "locker": { … },
    "valorLogisticaPremium": 0,
    "agente": { … },
    "marketplace": true,
    "blocklist": true,
    "cashback": { … },
    "progress": { … },
    "notasDevolucao": [ … ]
  }
}

Produtos

Ações relativas aos produtos constantes em uma solicitação de troca ou devolução.

Operations

Notas de devolução

Operações com notas fiscais de devolução.

Operations