Shipments inbound

Please see the Shipments Inbound documentation for help on transferring diamonds into a Tracr instance.

List inbound shipments

To list all inbound shipments:

Call GET /v2/shipment/inbound

{
    "next": null,
    "page": 1,
    "pages": 1,
    "previous": null,
    "results": [
        {
            "id": "rhgy6z6e7j1mwd11nbqc0urg",
            "name": "Rough Shipment",
            "sender": "https://api.producer.uat.tracr.com",
            "diamonds": [
                {
                    "created_at": "2024-05-31T11:31+0000",
                    "diamond_id": "nmg7r5yhut68fz4czxnvanoc",
                    "lifecycle_state": "rough",
                    "polished": null,
                    "rough": {
                        "carats": "0.64",
                        "colour": null,
                        "model": null,
                        "quality": null,
                        "stress": null,
                        "box_id": "demo_rough_box",
                        "sight_year": null,
                        "sight_number": null
                    },
                    "transfer_state": "transfer_in_confirmed",
                    "updated_at": "2024-05-31T11:31+0000"
                },
                {
                    "created_at": "2024-05-31T11:31+0000",
                    "diamond_id": "gy9zacqpt64rfm5l9aj8fdgc",
                    "lifecycle_state": "rough",
                    "polished": null,
                    "rough": {
                        "carats": "2.57",
                        "colour": null,
                        "model": null,
                        "quality": null,
                        "stress": null,
                        "box_id": "demo_rough_box",
                        "sight_year": null,
                        "sight_number": null
                    },
                    "transfer_state": "transfer_in_confirmed",
                    "updated_at": "2024-05-31T11:31+0000"
                }
            ],
            "created_at": "2024-05-31T11:31+0000",
            "shipment_type": "rough",
            "status": "action_required",
            "total_diamonds": 2
        },
        {
            "id": "ftduqi7nsiaw4vn0039va92v",
            "name": "Polished Shipment",
            "sender": "https://api.manufacturer.uat.tracr.com",
            "diamonds": [
                {
                    "created_at": "2024-05-31T14:35+0000",
                    "diamond_id": "a2uj544df5t5awu5v792wyj6",
                    "lifecycle_state": "polished",
                    "polished": {
                        "carats": "1.01",
                        "clarity": "SI1",
                        "colour": "F",
                        "cut_grade": "EX",
                        "shape": "Round"
                    },
                    "rough": null,
                    "transfer_state": "transfer_in_confirmed",
                    "updated_at": "2024-05-31T14:35+0000"
                },
                {
                    "created_at": "2024-05-31T14:35+0000",
                    "diamond_id": "jo55p0yxbk7slopptdwv0zol",
                    "lifecycle_state": "polished",
                    "polished": {
                        "carats": "0.31",
                        "clarity": "VVS1",
                        "colour": "F",
                        "cut_grade": "EX",
                        "shape": "Pear"
                    },
                    "rough": null,
                    "transfer_state": "transfer_in_confirmed",
                    "updated_at": "2024-05-31T14:35+0000"
                }
            ],
            "created_at": "2024-05-31T14:35+0000",
            "shipment_type": "polished",
            "status": "action_required",
            "total_diamonds": 2
        }
    ],
    "total": 2
}

This endpoint supports filtering. For example, to only return rough shipments from producers:

Call GET /v2/shipment/inbound?shipment_type=rough

{
    "next": null,
    "page": 1,
    "pages": 1,
    "previous": null,
    "results": [
        {
            "id": "rhgy6z6e7j1mwd11nbqc0urg",
            "name": "Rough Shipment",
            "sender": "https://api.producer.uat.tracr.com",
            "diamonds": [
                {
                    "created_at": "2024-05-31T11:31+0000",
                    "diamond_id": "gy9zacqpt64rfm5l9aj8fdgc",
                    "lifecycle_state": "rough",
                    "polished": null,
                    "rough": {
                        "carats": "2.57",
                        "colour": null,
                        "model": null,
                        "quality": null,
                        "stress": null,
                        "box_id": "demo_rough_box",
                        "sight_year": null,
                        "sight_number": null
                    },
                    "transfer_state": "transfer_in_confirmed",
                    "updated_at": "2024-05-31T11:31+0000"
                },
                {
                    "created_at": "2024-05-31T11:31+0000",
                    "diamond_id": "nmg7r5yhut68fz4czxnvanoc",
                    "lifecycle_state": "rough",
                    "polished": null,
                    "rough": {
                        "carats": "0.64",
                        "colour": null,
                        "model": null,
                        "quality": null,
                        "stress": null,
                        "box_id": "demo_rough_box",
                        "sight_year": null,
                        "sight_number": null
                    },
                    "transfer_state": "transfer_in_confirmed",
                    "updated_at": "2024-05-31T11:31+0000"
                }
            ],
            "created_at": "2024-05-31T11:31+0000",
            "shipment_type": "rough",
            "status": "action_required",
            "total_diamonds": 2
        }
    ],
    "total": 1
}

Accept a transfer

To accept an inbound shipment (thereby starting the transfer process), pass the list of the diamond IDs you wish to accept to the API, along with the ID of the shipment assigned by Tracr.

For example, to accept only the pear-shaped diamond in the polished shipment:

Call POST /v2/transfer/in/ftduqi7nsiaw4vn0039va92v/accept

Request

{
    "diamonds": [
        {
            "diamond_id": "jo55p0yxbk7slopptdwv0zol"
        }
    ]
}

Response

{
    "results": [
        {
            "diamond_id": "jo55p0yxbk7slopptdwv0zol",
            "status": "success"
        }
    ]
}

Reject a transfer

In a similar vein, diamonds can be rejected from the transfer. For example, to reject the round diamond:

Call, POST /transfer/in/ftduqi7nsiaw4vn0039va92v/reject

Request

[
    {
        "diamond_id": "a2uj544df5t5awu5v792wyj6"
    }
]

Response

[
    {
        "diamond_id": "a2uj544df5t5awu5v792wyj6",
        "status": "success"
    }
]

Please note

For shipments of rough diamonds, the shipment must be accepted or rejected in its entirety (i.e. by sending each diamond in the request body), otherwise no action will be taken.

For example: POST /v2/transfer/in/b66ei4prxlp3fx1lwd2zps7x/accept

{
    "diamonds": [
        {
            "diamond_id": "nmg7r5yhut68fz4czxnvanoc"
        }
    ]
}

{
    "message": "Rough shipments must be accepted, cancelled, or rejected in their entirety. All of the shipment's diamonds must be present in request."
}

In the case of rough shipments, once the transfer has been accepted you'll be able to start registering rough diamonds against the shipment using the box_id field. See (Register a diamond from another producer for more information.